PR0F.  M.  KLINE 
2b  wAVCHLY  PLACE 


AEC  Computing  and 
Applied  Mathematics  Center 


AEC  RESEARCH  AND  DEVELOPMENT  REPORT 


TiD-4500 

35th  Ed. 


NYO-1480-9 


THE  NU-SPEAK  SYSTEM 

by 


Judith  Glasner,  Stanley  Ocken, 

David  Rosenberg,  Jack  Schwartz, 

George  Shapiro  and  Alan  Silverman 

November  1964 


^ 


Courant  Institute  of  Mathematical  Sciences 


o 

~  I 

o  5 


NEW  YORK   UNIVERSITY 

NEW    YORK.    NEW    YORK 


This  report  was  prepared  as  an  account  of  Government  sponsored  work.  Neither 
the  United  States,  nor  the  Commission,  nor  any  person  acting  on  behalf  of  the 
Commission: 

A.  Makes  any  warranty  or  representation,  express  or  implied,  with  respect  to 
the  accuracy,  completeness,  or  usefulness  of  the  information  contained  in 
this  report,  or  that  the  use  of  any  information,  apparatus,  method,  or 
process  disclosed  in  this  report  may  not  infringe  privately  owned  rights;  or 

B.  Assumes  any  liabilities  with  respect  to  the  use  of,  or  for  damages  resulting 
from  the  use  of  any  information,  apparatus,  method,  or  process  disclosed 
in  this  report. 


As  used  in  the  above,  "person  acting  on  behalf  of  the  Commission"  includes 
any  employee  or  contractor  of  the  Commission,  or  employee  of  such  contractor, 
to  the  extent  that  such  employee  or  contractor  of  the  Commission,  or  employee 
of  such  contractor  prepares,  disseminates,  or  provides  access  to,  any  information 
pursuant  to  his  employment  or  contract  with  the  Commission,  or  his  employment 
with  such  contractor. 


UNCLASSIFIED 


AEC  Computing  and  Applied  Mathematics  Center 
Courant  Institute  of  Mathematical  Sciences 
New  York  University 


TlD-4500  NYO-1480-9 

35th  Ed. 

THE  NU -SPEAK  SYSTEM 

by 

Judith  Glasner,  Stanley  Ocken, 

David  Rosenberg,  Jack  Schwartz, 

George  Shapiro  and  Alan  Silverman 

November  1964 


Contract  No.  AT( 50-l)-l480 


-  1  - 
UNCLASSIFIED 


NYO-1^80-9 


ABSTRACT 

Nu-Speak  Is  a  list  processing  language  embedded 
in  PAP.   This  manual  describes  the  use  of  the  Nu-Speak 
system,  the  use  of  a  corresponding  Fortran  version  of 
the  system,  and  some  applications. 
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NYO-1480-9 
THE  NU-SPEAK  SYSTEM 

by 

Judith  Glasner,   Stanley  Ocken,   David  Rosenberg, 
Jack  Schwartz,   George  Shapiro  and  Alan  Silverman 

A .   Introduction. 

The  Nu-Speak  list  processing  system  Is  available  In 
two  versions,  a  Fortran  version  and  a  PAP  version.   In 
the  following  report,  the  use  and  some  of  the  underlying 
structure  of  both  versions  of  Nu-Speak  will  be  outlined. 
While  many  users  will  prefer  to  write  Nu-Speak  programs 
In  Fortran,  It  should  be  noted  that  only  In  the  FAP 
version  can  full  advantage  be  taken  of  Nu-Speak 
flexibility. 

Al.   Fortran  Nu-Speak. 

To  the  two  types  of  objects  normally  considered 
In  Fortran  •—  variables  and  arrays  —  Fortran  Nu-Speak 
adds  a  third  —  the  list.   The  logical  structure  of  a 
Nu-Speak  list  is  as  follows: 

Each  list  consists  of  a  finite  number  of  items .  Each 
item  is  of  one  of  three  types:   a  listhead,  a  link,  or  a 
data  item.   Each  list  contains  one  and  only  one  head,  called 
the  head  of  the  list.   The  remaining  items  of  the  list 
follow  in  serial  order,  the  last  item  being  followed  by 
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the  head  of  the  list.   Thus,  lists  have  a  kind  of  'looped' 
or  'circular'  form.   A  list  may  contain  no  items  other  than 
its  head  in  which  case  it  is  called  a  nullist.   If  squares 
designate  llstheads,  rhomboids  designate  links,  and  circles 
designate  data  items,  a  typical  list  might  he  represented 
as  follows 


Each  list  may  have  one  or  several  name s ;  the  name  of  a 
list  is  an  ordinary  Fortran  variable.   To  the  ordinary 
Fortran  system,  Nu-Speak  adds  a  number  of  functions  and 
subroutines  which  enable  the  manipulation  of  lists.   These 
subroutines  and  functions  are  as  follows:   NEXT,  PREV, 
READY,  SUBLIS,  ERASER,  HANG,  UNHANG,  NAMLIS,  C0PYT0,  JUMPT0, 
REM0VE,  CUPL,  NCPLT0,  GLERNM,  INSERT,  TYPE,  DSTR0Y,  CREATE, 
SAVER,  GETTER,  N0WW,  and  CURRNT,   A  final  set  of  subroutines, 
C0MEIN  and  C0M0UT,  enable  recursive  subroutines  to  be 
written  within  the  Nu-Speak  Fortran  system. 

One  other  concept,  not  present  in  the  ordinary  use  of 
Fortran,  enters  the  Nu-Speak  Fortran  system.   At  any  given 
step  of  Nu-Speak  list  processing,  we  will  say  that  the 
computer  is  looking  at  or  examining  a  given  item  on  a  given 
list.   The  manner  in  which  the  various  Nu-Speak  list  processes 
affect  the  list  item  at  which  the  computer  is  looking  will  be 
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explained  In  what  follows. 

The  Initialising  command 

CALL   READY 
should  be  the  first  command  of  any  Portran/Nu-Speak  main 
program.   This  prepares  the  computer  for  list  processing 
and  recursive  function  usage. 

A  list  is  created  by  the  Fortran  statement 

CALL    CREATE  (LIST)  j 

here  LIST  is  a  Fortran  variable  which  becomes  the  name  of 
the  newly  created  list.   The  list,  when  created,  is  a 
nullist.   The  computer  is  left  examining  the  head  of  the 
newly  created  nullist. 

Suppose  now  that  the  computer  is  examining  a  given 
item  on  a  given  list.   The  Fortran  statement 

A  =  TYPE  (DUMMY) 

will  make  the  variable  A  positive  if  the  item  currently 
being  examined  is  a  data  item,  zero  if  the  item  currently 
being  examined  is  a  link,  and  negative  if  the  item 
currently  being  examined  is  a  head.   Here,  DUMMY  is  any 
arbitrary  Fortran  variable,  needed  only  for  compatibility 
between  Fortran  and  the  underlying  Nu-Speak  programs. 
After  executing  this  statement,  the  computer  is  left 
examining  the  same  list  element  as  before.   The  function 
TYPE  can  also  be  used  in  Fortran  statements  of  IF-kind . 
Thus,  the  statement 

IP  (TYPE  (DUMMY))  1,2,3 
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will  transfer  control  to  statements  1,  2  or  3  of  a  program, 
depending  on  whether  the  list  element  under  examination  by 
the  computer  is  a  head,  a  link,  or  a  data  item. 

Suppose  again  that  the  computer  is  examining  a  given 
item  on  a  given  list.   The  Fortran  statement 

CALL   NEXT  (DIDMY) 
will  cause  the  computer  to  examine  the  next  item  on  the 
given  list.   The  Fortran  statement  CALL  PREV ( DIMMY )  will 
cause  the  computer  to  examine  the  previous  item  on  the 
given  list.   The  Fortran  statements 

CURREN  =  PREV  (DUMMY) 
and 

CURREN  =  NEXT  (DUMMY) 
will  cause  the  computer  to  examine  the  previous  and  the 
next  element  on  the  given  list  respectively,  and  will  set 
the  variable  CURREN  equal  to  the  previous  or  the  next  list 
item  respectively.   (If  this  previous  (resp.  next)  item 
is  a  listhead  or  a  link,  the  variable  CURREN  will  be  set 
equal  to  a  mysterious  octal  integer.) 

The  Nu-Speak  functions  can  be  compounded  in  the 
manner  usual  in  Fortran.   Thus  the  statement 

VAR  =  TYPE  (PREV(NEXT(DUIVDyrY))) 
is  legitimate,  and  has  the  same  effect  as 

VAR  =  TYPE(DUM^)  . 
The  Fortran  statement 

CALL    INSERT(E) 
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will  insert  the  value  of  the  expression  E  on  the  list 
currently  being  examined,  immediately  after  the  item 
currently  being  examined.   The  computer  will  be  left 
examining  the  newly  inserted  item.   Thus,  e.g.,  suppose 
that  the  variables  A(l) , . . . ,A(6)  are  the  data  words  N0W, 
IS,  TIME,  P0R,  ALL,  G00D,  read  in  from  the  input  tape 
using  an  a6  format.   Then  the  code 


CALL 

CREATE (LISTl) 

D0  7 

I  =  1,6 

CALL 

INSEKT(A(I)) 

7   CALL 

PREV(DUMf^) 

will  create  a  Nu-Speak  list  named  LISTl,  and  containing 
the  six  data  items  G00D,  ALL,  F0R,  TIME,  IS,  N0W  in  that 
order.   Note  also  that  at  the  end  of  this  particular 
do-loop,  the  computer  will  be  left  examining  the  head  of 
LISTl.   The  function  INSERT  can  also  be  used  in  the  form 

B  =  INSERT (A)  , 
which  has  the  same  effect  as 

CALL  INSERTXA)    '  ' 

B  =  A 
The  inverse  function  to  INSERT  is  performed  by  REM0VE, 
which  may  be  used  either  in  the  form 

CALL   REM0VE  (DUMMY) 

or 

VAR  =  REM0VE  (DUMMY) 


Both  of  these  lines  of  code  remove  froin  a  list  the 
single  particular  item  at  which  the  computer  is  looking, 
and  cause  the  computer  to  look  at  the  immediately  follow- 
ing item.   The  second  of  the  above  lines  of  code  also  sets 
the  variable  VAR  equal  to  the  value  of  the  immediately 
following  data  item  (or  to  a  mysterious  octal  number  if 
the  following  item  is  a  link  or  a  head)  . 

The  function  JUMPTJZJ  is  used  in  the  form 
CALL    JUMPT0  (LIST)  , 
whose  LIST  is  the  name  of  a' previously  created  list. 
This  code  will  cause  the  com.puter  to  examine  the  head  of 
the  list  named  LIST.   Thus,  e.g.,  to  count  the  number  of 
items  in  a  list  named  LIST,  we  may  use  the  following  code. 

CALL   JUMPT0  (LIST) 
N  =  0 
11     IP   (TYPE(NEXT(DU]yD}/[Y)))2,l,l 

1  N  =  N  +  1 
G0  T0  11 

2  ...  [here  follows  the  rest  of  program] 

If  it  is  desired  to  erase  a  list  once  created,  the 
code 

CALL   ERASER  (LIST) 
may  be  used.   This  will  cause  the  list  named  LIST  to  be 
erased,  and  the  storage  cells  which  this  list  formerly 
occupied  to  be  returned  to  a  master  'junkpile'  of  space 
available  for  re-use.   It  is,  of  course,  quite  important 
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to  erase  lists  when  the  data  represented  by  them  Is  no 
longer  of  use.   After  a  call  to  ERASER  of  this  sort,  the 
computer  will  be  left  looking  at  the  same  data  word  of 
the  same  list  at  which  it  was  looking  at  the  time  of  the 
call.   If,  however,  the  list  erased  happens  to  contain 
the  element  at  which  the  computer  was  looking,  then, 
after  the  erasure,  the  computer  is  no  longer  looking 
at  any  item.   To  recommence  list  processing,  a  statement 
either  of  the  type 

CALL     JUMPT0  (LIST) 
or 

CALL    GETTER (VAR)   (cf.  below) 
or 

CALL    CREATE  (LIST) 

must  be  executed.   A  list  should  never  be  erased  more 
than  once,  nor  should  a  nonexistent  list  ever  be  erased. 

If  the  computer  is  looking  at  the  head  of  a  list, 
the  statement 

CALL     C0PYT0  (VAR) 
will  cause  it  to  produce  a  copy  of  the  list  at  whose 
head  it  is  looking,  and  to  make  the  variable  VAR  into  a 
name  of  the  copied  list.   After  the  command  is  executed, 
the  computer  will  be  left  looking  at  the  head  of  the 
newly  produced  copy. 

Suppose  that  the  computer  is  looking  at  a  given 

item  on  a  given  list.   Then  the  statement 

CALL     NCPLT0  (VAR) 
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will  cause  the  computer  to  break  the  list  at  which  it  is 
looking  into  two  parts.   The  first  part  will  consist  of 
all  items  up  to  and  including  the  item  at  which  the 
computer  was  looking;  the  second  part  will  consist  of  all 
remaining  items.   The  first  part  of  the  list  will  have 
same  name  (or  names)  as  it  originally  had;  the  second  will 
receive  the  name  VAR.   Thus,  e.g.,  if  the  Fortran  variables 
A(l) , . . . ,A(6)  are,  as  previously,  the  data  words  N0W,  IS, 
TIME,  F0R,  ALL,  G00D,  the  code 

CALL    CREATE (LISTl) 

D0  7    I  =  1,6 

CALL    INSERT (A(I)) 
7   CALL    PSEV( DUMMY) 

CALL     C0PYT0(LIST2) 

A  =   NEXT(NEXl'(NEXT(DU]y[MY))  ) 

CALL    NCPLT0(LIST5) 

would  result  in  the  production  of  three  lists:   LISTl, 
consisting  of  a  head  and  of  the  data  items  G00D,  ALL, 
F0R;   LIST2,  consisting  of  a  head  and  of  the  data  items 
G00D,  ALL,  P0R,  TIME,  IS,  N0¥;   and   LIST3,  consisting 
cf  a  head  and  of  the  data  items  TIME,  IS,  N0W, 

The  inverse  of  NCPLT0  is  CUPL,  which  may  be  used 
either  in  the  form 

CALL    CUPL (LIST) 
or 

VAR  =   CUPL (LIST) 
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The  action  of  these  commands  Is  as  follows:   Suppose  that 
the  computer  Is  looking  at  a  given  element  on  a  given  llst^ 
say^  LISTl.   Then  either  of  the  above  commands  will  cause 
the  whole  body  of  the  list  named  LIST  (except  its  head)  to 
be  interpolated  into  LISTl  immediately  following  the 
element  at  which  the  computer  was  looking,  and,  immediately 
preceding  what  was  originally  the  next  following  item. 
In  this  process,  the  LIST  being  UUPL-d  loses  its  head  and 
its  separate  identity;  its  head  is  automatically  returned 
to  a  junkpile  of  free  heads  for  reuse.   The  computer  is 
left  looking  at  the  first  inserted  item.   The  second  of 
the  above  form  of  the  CUPL  command  sets  the  value  of  the 
variable  VAR  equal  to  the  first  inserted  item  in  addition 
to  performing  the  above  functions. 

Thus,  if  the  Fortran  variables  A  and  B  are  the  data 
words  AXE  and  BOX,  the  code 

CALL     CREATE (LISTl) 

CALL     CREATE (LIST2) 

D0  7      J  =1,3^: 

CALL     JUMPT0 ( LISTl ) 
CUR   =   INSERT (A) 
CALL     JUMPT0(LIST2)' 
7    CUR   =   INSERT (B) 

CUR   =   NEXT (DUMMY) 
CUR   =   CUPL (LISTl) 
would  leave  LIST2  consisting  of  a  head  and  of  the  data 
items  BOX,  BOX,  AXE,  AXE,  AXE,  BOX;  LISTl  would  no  longer 
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exist,  though  it  could  be  recreated  as  a  nullist,  if 
desired,  by  the  subsequent  command 

CALL    CREATE (LISTl)  . 
We  also  note  that  in  the  above  coding,  the  final  value 
of  the  variable  CUR  is  AXE,  and  that  the  computer  is 
left  looking  at  the  first  item  AXE  on  LIST2. 

The  function  of  a  link  is  to  designate  a  list  as 
a  sublist  of  the  list  on  which  the  link  occurs.   Each 
link  'points'  in  this  sense  to  some  sublist.   To  intro- 
duce such  a  link,  the  command 

CALL    HANG (LIST) 
is  used.   This  command  will  interpolate  a  link  pointing 
at  the  list  named  LIST  immediately  after  the  item  at 
which  the  computer  was  looking;  the  computer  is  then 
left  looking  at  the  newly  inserted  link.   To  remove  a 
link  at  which  the  computer  is  looking,  the  inverse 
command 

CALL    UNHANG  ( DUMiyiY ) 
or 

CUR   =   UNHANG (DUMMY) 
should  be  used.   This  will  remove  the  link  and  leave 
the  computer  looking  at  the  item  which  had  followed 
the  link.   The  second  of  the  above  forms  of  the  UNHANG 
command  will  also  set  the  variable  CUR  equal  to  the 
value  of  the  next  following  item  in  addition  to  perform- 
ing the  above  functions. 

If  the  computer  is  looking  at  a  link,  the  command 


CALL    SUBLIS( DUMMY) 
will  cause  the  computer  to  look  at  the  head  of  the 
sublist  at  which  the  link  points.   In  this  way  the 
computer  can  proceed  from  a  list  to  one  of  its 
sublists . 

In  terms  of  the  symbols  for  heads,  links,  and  data 
introduced  above,  a  typical  'list  structure'  of  lists 
and  sublists  might  be  represented  as  follows: 


HEAD  -^r_ /"A  _) KLI^>— (^^)-— (^J)— <U^ 


^ 


HEAD 


\CKxy 


It  is  even  possible  that  a  sublist,  say  LIST2,  of  a 
certain  list,  say  LISTl,  should  itself  have  LISTl  as 
a  sublist,  or  even  that  LISTl  should  be  a  sublist  of 
itself,  a  situation  represented  graphically  by  a 
diagram  such  as  the  following 


HEAD /~^) J^ J^^^^^^^ 


It  is  vital  to  the  proper  functioning  of  Nu-Speak  that 
no  sublist  of  a  list  ever  be  erased  before  the  list 
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Itself  Is  erased.   If  the  subllst  is  to  be  erased,  It 

should  be  'unhung'  first.  Thus,  the  code 

CALL  CREATE (LISTl) 

'CALL  CREATE (LIST2) 

CALL  HANG (LISTl) 

CALL  ERASER (LISTl) 


is  inadmissible,  while 

CALL  CREATE (LISTl) 

CALL  CREATE (LIST2) 

CALL  HANG (LISTl) 

CALL  UNHANG (LISTl) 

CALL  ERASER (LISTl) 

is  admissible. 

The  requirement  that  no  subllst  of  a  list  be  erased 
before  the  main  list  is  erased  naturally  makes  it  difficult 
to  deal  with  such  'reflexive'  structures  as  the  one 
pictured  Just  above.   For  an  account  of  the  prcoedures  to 
be  employed  in  dealing  with  such  structures,  see  the 
section.  Special  procedures  for  dealing  with  self-reflexive 
list  structures,  in  the  attached  FAP-Nu-Speak  manual. 

The  command  NAMLIS  has  the  form 

CALL   NAMLIS (VAR) 
where  VAR  is  a  Fortran  variable.   Its  effect  is  to 
designate  VAR  as  a  name  of  the  list  at  (an  element  of) 
which  the  computer  is  looking.   The  inverse  operation  to 
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NAMLIS  is  provided  by  the  command  CLERNM,  which  has  the  form 

CALL     CLERNM(NAME)  , 
and  which  frees  the  variable  NAME  from  being  a  list  name. 
Both  commands  CLERNM  and  NAMLIS  leave  the  item  at  which 
the  computer  is  looking  unaltered.   Thus  the  code 

CALL     CREATE (LISTl) 

CALL    CREATE (LIST2) 

CALL     NAMLIS (T0M) 

CALL    NAMLIS (DICK) 

CALL     NAMLIS  (HARRY^I 

CALL     JUMPT0( LISTl) 

CALL     NAMLIS (J0E) 

CALL    NAMLIS (T0M) 

CALL     CLERNM (DICK) 
will  leave  the  list  named  LISTl  with  the  two  additional 
names  J0E  and  T0M,  and  the  LIST  named  LIST2  with  the 
single  additional  name  HARRY.   The  variable  DICK  will 
not  be  a  list  name. 

The  functions  CURRNT  and  N0¥W  permit  the  user  to 
obtain  the  current  data  item.   In  particular,  performing 
arithmetic  may  have  destroyed  the  MQ,  register  which 
contained  the  current  data  item. (see  "conventions  involved 
in  looking  at  a  list  element'  in  Sec.  B4  of  the  Nu-Speak 
PAP  Section  of  this  manual).   Either 

X   =   CURRNT  (DUMMY) 

or 

I   =   N0W¥  (DUM^IY) 
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will  restore  the  MQ  and  set  the  left  hand  side  to  the 
current  data  item.   CURRENTand  N0WW  are  identical  except 
that  the  former  should  be  used  for  floating,  alphabetic 
or  boolean  data  and  the  latter  for  integer  data. 

Similarly,  all  the  function  type  subprograms  in 
Nu-Speak  have  alternate  but  equivalent  names  in  the 
opposite  mode.   Specifically 

FIXED  FL0ATING 

NEXT  PNEXT 

IPREV  PREV 

NHANG  UNHANG 

IREM0V  REM0VE 

INSERT  FINSRT 

ICUPL  CUPL 

ITYPE  TYPE 

In  assignment  or  IF  statements  care.. mast  be  taken 
to  use  the  name  with  the  appropriate  mode.   In  CALL 
statements,  of  course,  either  name  may  be  used. 

It  may  now  be  mentioned  that,  as  Nu-Speak  list 
processing  proceeds,  a  running  count  of  the  number  of 
current  references  to  each  list  is  kept.   This  number 
is  defined  as  the  sum  of  the  number  of  names  of  a  list 
and  the  niimber  of  links  pointing  to  the  list.   If  this 
number  reaches  0  (logically  implying  that  there  is  no 
way  of  referring  to  the  list),  the  list  concerned  is 
automatically  erased.   The  following  coding,  with 
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coniments,  will  Illustrate  the  points  involved 


CALL  CREATE ( LIS Tl) 

CALL  CREATE (LIST2) 

CALL  NA]yLIS(T0M) 

CALL  NAMLIS(DICK) 

CALL  NAMLIS ( HARRY ) 

CALL  CLERNM(DICK) 

CALL  JUMPT0(LIST1) 

CALL  HANG(T0M) 

CALL  CLERNTy[(LIST2) 

CALL  CLERN]y[(T0M) 

CALL  CLERNM(  HARRY) 

THIS  =  UNHANG  (DUM^TY) 


LISTl  HAS  1  REF. 

LIST2  HAS  1  REP. 

LIST2  HAS  2  REPS 

LIST2  HAS  3  REPS 

LIST2  HAS  4  REPS 

LIST2  HAS  5  REPS 

LIST2  HAS  h   REPS 
'LIST2'  HAS  3  REPS 
'LIST2'  HAS  2  REPS 
P0RMER  'LIST2'  HAS  1  REP, 
N0  NAME  ANY  L0NGER 
P0RMER  'LIST2'  L0SES  ALL 
REPS,  IS  AUT0MATICALLY 
ERASED . 

The  coinmand  DSTR0Y  has  the  form 
CALL   DSTR0Y(LIST) . 

Its  effect  is  to  erase  the  designated  list,  all  its 
sublists,  all  their  sublists,  etc.,  thus  erasing  an 
entire  list  structure  with  a  single  command.   It  should 
never  he  used  if  the  list  structure  contains  lists  which 
are  sublists  of  more  than  one  list,  that  is,  if  the  list 
structure  is  not  'treelike.' 
The  instructions 
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CALL   SAVER (A) 

and 

CALL   GETTER (A) 
are  used  to  'remember'  the  item  at  which  the  computer  was 
looking  at  a  given  point  in  a  list  manipulation  process, 
in  order  to  be  able  to  return  to  it  later.   The  notation 
of  the  item  is  made  with  SAVER,  and  return  may  subsequently 
be  made  with  GETTER.  The  variable  A  occurring  in  SAVER  or 
GETTER  should  have  ■'■'a    Fortran  DI]yiENSI0N  of  J>. 

The  user  is  warned  that  SAVER  and  GETTER  will  work 
properly  only  if  noMl&ts  are  created  either  by  CREATE  or 
by  C0PyT0  between  a  given  use  of  SAA/ER  and  the  correspond- 
ing subsequent  use  of  GETTER.   Thus,  e.g.,  suppose  that  the 
computer  is  at  a  given  moment  examining  a  given  item  on  a 
list  named  LIST.   Then  the  code: 

CALL  SAVER (A) 

CALL  JUMP T0 (LIST) 

CALL  C0PYT0(LIST2) 

CALL  GETTER (A) 

may  fail  to  bring  the  computer  back  to 'the  list  element 
originally  under  examination.   To  return  to  a  list  element 
even  after  an  ensuing  list  creation,  the  following  more 
round  about  coding  can  be  used. 
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BREAK  INT0  T¥0  PARTS 


C0PIES  FIRST  PART 


C0PIES  SEC0ND  PART 


J0INS  FIRST  AND  SECOND  PARTS 


CALL    NCPLT0 ( AUXLIS ) 

CALL    JUMPT0(LIST) 

CALL    C0PYT0(LIST2) 

CALL    JUMPT0 ( AUXLIS ) 

CALL    C0PYT0(AUX2) 

CALL    JUMPT0(LIST2) 

CALL    PREV( DUMMY) 

CALL    CUPL(AUX2) 

CALL    JUMPT0(LIST) 

CALL    PREV( DUMMY) 

CALL    CUPL( AUXLIS)        REST0RES  LIST  T0  FIRST 

C0NDITI0N 

CALL    PREV  G0ES  BACK  T0  0RIGINAL 

ELEMENT 

To  enable  the  use  of  recursive  processes  within  the 
Nu-Speak/Fortran  system,  two  auxiliary  subroutines,  C0MIN 
and  C0I^UT,'  are  provided.   These  subroutines  provide  for 
the  recursive  bookkeeping  of  the  non- input  and  non-output 
variables  which  are  used  within  the  recursive  subroutine. 

The  definition  of  a  Fortran  subroutine  which  is  to 
be  used  recursively  and  which  uses  internal  variables 
should  begin: 

SUBR0UTINE   NAME(Llst  of  subroutine  arguments) 

CALL    ''CpfMIN(L0C,  list  of  internal  variables  of 

the  subroutine  and  their  dimensions); 

here  L0C  is  to  be  a  Fortran  variable  not  used  otherwise 

in  the  subroutine,  except  In  a  CALL  C0M0UT  statement  (see 
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below) .   The  remaining  argument  list  of  C0MEIN  will  have 
the  form  VARl,  dimension  of  VARl,  VAR2,  dimension  of  VAR2, 
...,  etc.  The  internal  variables  of  a  subroutine  are 
those  variables  whose  values  must  be  preserved  around  a 
recursive  call  to  the  subroutine. 

When  a  recursive  subroutine,  say  PR0CES,  is  to  call 
itself,  the  statement: 

CALL      PR0CES  (list  of  arguments) 
may  not  be  used.   Instead,  a  call  of  the  form: 

CALL      DUMMY  (list  of  arguments) 

should  be  used  where  DUMMY  is  a  user  coded  FAF  subroutine 

(see  RECURSIVE  SUBROUTINES  in  the  FAF  section  of  this 

manual)  of  the  following  form: 

1      8 16 73 

*       FAF 

ENTRY   DUMMMY   (Note:  Nu-Speak  subroutines  should 

have  six  letter  names.) 

REWIND  16 

UPDATE  16 

REWIND  16  .  NSIZZZZZ 

SUBR  DUMMY, INPUTS,  (list  of  input  args  ) , 

ETC  0UTPTS,  (list  of  output  args) 

CALL  PR0CES,  list  of  args. 

RETPRM  DUMMMY 

END 
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All  dummy  recursion  programs  in  a  job  may  be 
included  in  a  single  FAP  deck;  each  routine  having 
an  ENTRY  card  (before  the  first  REWIND  card)  as 
well  as  SUBR,  USE,  RETPRM,  and  FINI  cards. 

Finally,  any  RETURN  statement  in  the  F0RTRAN 
subroutine  must  be  preceded  by  the  statement 

CALL     'C0M0UT(L0C) 
where  L0C  is  the  variable  which  occurs  as  the  first 
argument  of  the  CALL  C0MEIN  statement  of  the  subroutine 

A  number  of  restrictions  attach  to  the  use  of 
recursive  subroutines  in  Fortran/Nu-Speak. 

1.  A  recursive  CALL  statement  should  not  occur 
within  a  do-loop.   Thus 

D0  7    J  =  1,10 

•  •  • 

CALL    PR0CES(ARG1,ARG2) 
7    C0NTINUE 
is  illegal.   More  generally,  one  should  never  CALL  from 
within  a  do-loop  to  a  routine  which  might  directly  or 
indirectly  CALL  back  to  the  calling  routine. 

2.  A  Fortran/Nu-Speak  program  involving  recursion 
is  required  to  use  the  Fortran  standard  error  procedure. 

3.  Error  messages  and  termination  of  execution 
will  result  from  attempts  to  execute  various  illegal 
operations  (e.g.  REM0VE  a  listhead,  C0PYT0  when  not 
looking  at  a  listhead,  etc.).   These  error  messages 
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should  in  each  case  be  self-explanatory. 

The  true  power  and  efficiency  of  the  Nu-Speak 
recursive  subroutine  feature  can  best  be  realized  In 
the  Nu-Speak  FAP  system.   Programs,  then,  which  center 
on  recursiveness  should,  whenever  possible,  be  coded 
in  FAP. 

Fortran/Nu-Speak  list  operations  are  executed  by 
the  routines  described  in  additional  detail  in  the 
following  FAP/Nu-Speak  section  of  the  present  manual. 
A  user's  Fortran  program  reaches  these  underlying 
programs  after  transit  through  a  short  interface 
program.   Thus  the  user  may  consult  the  PAP/Nu-Speak 
section  of  this  manual  for  additional  details  on  the 
operation  of  the  Nu-Speak  system  required  from  time 
to  time.   By  reading  a  listing  of  the  interface  program 
it  should  be  possible  to  clear  up  even  the  most  subtle 
of  difficulties . 

A2.   The  Chaining  Requirement . 

The  main  link  of  a  Portran/Nu-Speak  job  must  be 

designated  as  a  chain  job  with  a  card  *   CHAIN(101,3) 

preceding  the  job.   A  two  card  binary  program 

designated  as  *   CHAIN  (102,5)  is  provided;  this  calls 

in  a  library  program  containing  final  error  messages  as 

required.   This  second  link  program  must  follow  the  main 

link  (*  CHAIN(101,3)),  and  generally  conform  to  all  the 

standard  Fortran  rules  for  chain  jobs. 
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B.   FAP  Nu-5peak. 
Bl .   Introduction. 

The  FAP  Nu-Speak  System  Is  embedded  in  FAP.   Thus 
the  user  writes  a  program  of  PAP  type,  and  may  write  any 
709^  machine  operation  code,  any  FAP  pseudo-operation, 
and  may  make  use  of  the  FAP  macro-operation  feature. 
To  the  basic  FAP  package,  Nu-Speak  adds  a  number  of  macros 
and  associated  programs.   These  macros  and  programs  fall 
naturally  into  seven  groups. 

a.   The  first  set  of  macros  belongs  to  the  basic 
subroutine  package,  providing  for  a  completely  recursive 
system  of  subroutine  calls,  with  automatic  freezing  and 
unfreezing  of  stored  data  on  a  pushdown  list  as  necessary. 
A  debugging  feature  and  a  number  of  arithmetic  macros, 
which  make  up  for  the  absence  of  Fortran-type  compiling, 
are  also  provided. 

The  macros  of  this  group  are  SUBR  (creates  a  recur-  ■ 
sively  usable  subroutine),  INTARS  (provides  storage  for 
the  internal  arguments  of  a  subroutine),  RETFRM  (return 
from  a  subroutine),  USE  (use  a  subroutine),  FINI  (desig- 
nates the  end  of  a  subprogram),  DgfBEG    (begins  a  do-loop), 
D^END  (ends  a  do-loop),  RD0BEG  (begins  a  recursive 
do-loop),  RDEND  (ends  a  recursive  do-loop),  USESV4 
(explained  below),  CALSV4  (explained  below),  DEBUG 
(assemble  subroutine  including  debug  feature  to  provide 
report  on  entry  and  leaving),  BEGSTK  (reserve  a  storage 
area  for  a  pushdown  stack),  PUTIN  (put  contents  of  AC  into 
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pushdown  stack),  TAKFRM  (fill  accumulator  from  top  of 
pushdown  stack),  and  CNTSTK  (counts' the  number  of  entries 
In  a  stack)  .   The  arithmetic  m.acros  are  ARITH,  ARITHA, 
PL0AT,  and  PL0ATA .   Two  additional  macros  KEPT  and  STEP 
are  provided  as  debugging  aids .   The  use  of  most  of  these 
features  will  be  made  plain  to  the  FAP-writer  by  the  follow- 
ing program  to  calculate  Ackerman's  recursive  function. 
CALL      NimAT,5.P0RMTl,A,l,B,l 


USE 

ACKERM, (A,B),C 

CALL 

NU¥AT,6,P0RMT2,C,1 

CALL 

EXIT 

A 

ESS 

1 

B 

BSS 

1 

P0RMT1 
P0RMT2 

[Appr 

'opriate  fomnat  should  be  include 

SUBR 

ACKKKM, INPUTS, (A,B) ,0UTPTS,C 

CLA 

A 

SUB 

=1 

TMI 

IPAISO 

ST0 

AMINSl 

CLA 

B 

SUB 

=  1 

TMI 

IPBISO 

ST0 

PMINSl 

USE 

ACKERM; (A,BMINS1) , VALUE 
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USE 

ACREHM, (AMINS 1, VALUE) ,C 

RE'l'^'KM 

ACK  h;KM 

IPAISO 

CLA 

B 

ADD 

=  1 

ST0 

C 

RETPRM 

ACK  KKM 

Il^'BISO 

USE 

ACKKKM, (AMINS1,=1),C 

RETFRM 

ACK  h'.KM 

INTARS 

( AMINS 1 , BMINS 1 , VALUE ) 

PINI 

b .   The  second  set  of  macros  constitutes  half  of  the 
total  list  package  and  enables  all  operations  on  lists 
without  subllsts,  that  is,  on  strings.   It  includes 
NEXT  (get  next  element  of  a  list),  PREV  (get  previous 
element),  JUMPT0  (jump  to  the  beginning  of  a  list), 
CUPL  (couple  two  lists  into  a  single  list),  NCPLT0  (break 
a  list  into  two  parts),  ERASER  and  ERAS0R  (for  erasing 
lists),  INSERT  (inserts  a  data  item  on  a  list),  REM0VE 
(deletes  a  data  item  from  a  list,  TEHEAD  (tests  for  a 
list  head),  and  TEDATA  (tests  a  data  element).   Other 
macros  in  this  group  are  CREATE  (creates  a  list),  NAMLIS 
(designates  a  variable  as  the  name  of  a  list),  CLERNM 
(frees  a  list  name  to  name  another  list),  RELEAS  (releases 
a  formerly  reserved  block  of  storage  to  freespace),  and 
C0PYT0  (forms  a  copy  of  a  list).   This  set  of  macros  makes 
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use  of  the  programs  which  maintain  a  list  of  free  space 
and  provide  free  space  as  needed  for  the  other  operations. 
These  latter  programs  are  entered  by  the  macros  RREESP 
(provides  free  space  for  new  list  elements),  and  FREEHD 
(provides  free  space  for  new  list  heads).  A  final  macro, 
READY,  Initializes  for  list  operations. 

In  advancing,  via  NEXT  or  PREV,  from  one  list  element 
to  another,  the  data  item  of  the  new  list  element  appears 
in  the  MQ  register. 

The  following  program  section,  which  Interchanges 
the  first  two  elements  of  a  list  named  LISTA,  and  then 
changes  the  name  of  the  list  to  LISTS  will  Illustrate  the 
use  of  some  of  the  above  features. 

JUMPT0    LISTA       JUMP   T0  HEAD  0P  LISTA 


NEXT 

STQ 

REM0VE 


ST0RIJ 


INSERT    ST0RIJ 


CLERNM 
NAMLIS 


LISTA 
LISTB 


N0¥  EXAMINING  FIRST  ENTRY 
SAVE  DATA  ITEM 
DELETES  FIRST  DATA  LEFT 
L00KING  AT  SEG0ND  ITEM 
INSERTS  DATA  ITEM  IN 
ST0RIJ  AFTER  SEC0ND  ITEM 
FREES  NAME  F0R  0THER  USE 
GWES  NEW  NAME  T0  PRESENT  LIST 


ST0RIJ   BSS        1 

c.   The  third  set  of  macros  constitutes  the  remainder 
of  the  list  package,  and  enables  operations  on  lists  with 
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subllsts.   This  group  of  macros  Includes  HANG  ("hangs" 
a  list  as  a  subllst  of  another  list),  UNHANG  (removes  a 
subllst  from  a  list),  TELINK  (tests  a  list  element  to 
see  If  it  is  a  pointer  to  a  sublist),  SUBLIS  (descends 
to  a  suhlist  through  such  a  pointer),  and  DSTR0Y  (erases 
a  list  and  all  its  sublists).   The  following  program,  to 
find  and  enter  the  first  sublist  of  a  list,  if  any  such 
sublists  exist,  will  illustrate  the  use  of  some  of  these 
macros . 

JUMPT0    LISTA 
L00P     NEXT  G0  T0  NEXT  ELEMENT 

TELINK  HAVE  WE  P0UND  A  SUBLIST? 

TRA        SBPIND   IF  S0,  TRANSFER  0UT  0F  L00P 

TEHEAD  ARE  WE  AT  END  0F  LIST? 

TRA       L00P     IF  N0T,  C0NTINUE  IN  L00P 


SBFIND  SUBLIS 


IF  SUBLIST  P0INTER  F0UND, 
DESCEND  T0  SUBLIST. 


d.   The  fourth  set  of  macros  constitutes  a 
miscellaneous  set,  some  of  which  are  not  particularly 
intended  for  ordinary  use  by  the  programmer  using 
Nu-Speak,  but  which  may  be  so  used,  if  desired.   This 
fourth  set  includes  ERASYR  (for  deleting  a  link), 
PRNTMC  (replaces  the  PAP  pseudo-op  PMC  to  assure  print- 
ing of  macro-cards  in  an  assembly) ,  HEADER  (provides  a 
heading  character),  and  a  few  others  described  in  more 

detail  below.  ^„ 
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e.  The  fifth  set  of  macros  pertains  to  the  special 
Nu-Speak  input/output  system  provided  as  an  option,  and 
will  be  explained  later  in  this  manual. 

f .  The  sixth  set  of  macros  provides  for  the  manipu- 
lation of  BCD  letters  within  data  words  in  a  manner  similar 
to  the  manipulation  of  data  words  within  blocks. 

g.  The  seventh  set  of  macros  are  intermediate  macros, 
used  by  the  system  for  the  definition  of  the  macros  listed 
above,  which  the  programmer  will  practically  never  use,  and 
which  he  must  know  about  only  in  order  to  avoid  defining 
macros  with  the  same  name  (which  would,  of  course,  destroy 
the  whole  house  of  cards) .   These  macros  have  names  of 

6  characters  starting  with  two  periods. 

The  Nu-Speak  user  interested  in  saving  core  space 
will  be  able  to  use  only  part  of  the  system,  rather  than 
the  whole.   The  three  options  provided  are: 

(a)  The  small  economy  size.   Only  the  recursive 
subroutine,  list,  and  string  macros. 

(b)  The  macros  of  (a)  and  the  arithmetic  package. 

(c)  The  whole  works. 

An  additional  core  storage  saving  is  provided  by  the 

WRITE  m.acro  of  the  Nu-Speak  1/0  system  (described  below) 

which  uses  chaining  to  restrict  main-line  l/0  operations 

to  binary  operations  using  (I0B),  thereby  saving  2,000 

words  which  otherwise  would  be  occupied  by  various  programs 

of  the  (I0H)  complex.   Note  however  that  use  of  the  DEBUG 

feature  of  Nu-Speak  (which  uses  NUWAT)  will  call  in 
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the  (I0H)  complex,  thus  requiring  extra  space. 

Again  as  a  space-saving  measure,  various  terminal 
error  messages  and  programs  are  relegated  to  a  third 
chain  link. 

B2,   Allocation  of  core  storage  in  Nu-Speak. 

Core  storage  in  Nu-Speak  will  normally  be  allocated 
as  follows: 

(a)  At  bottom,  the  100  reserved  system  locations. 

(b)  Then  the  program  area,  including  blocks 
reserved  for  linear  or  other  Fortran  type  arrays. 

(c)  Prom  the  end  of  the  program  area  to  the  bottom 
of  common,  the  listspace  and  pushdown-list  area,  divided 
as  follows: 

(cl)   an  area,  growing  upwards,  in  which  occupied 
and  free  llstheads  are  found; 

(c2)   an  area  above  this,  growing  upwards,  in  which 
occupied  and  once  used  but  presently  unoccupied  list  cells 
are  found; 

(c3)   an  ever-shrinking  area  of  the  still  unused  core, 
bounded  below  by  the  listspace  area  and  above  by  the 

(c4)   pushdown  list  area  associated  with  the  recur- 
sive use  of  subroutines,  growing  downward  from  upper  core 
and  shrinking  back  up  as  recursions  proceed; 

(d)  The  common  area  near  the  top  of  core; 

(e)  The  usual  desolate  area  of  erasable  common  at 
the  very  top  of  core. 
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The  boundaries  of  all  these  various  areas  of  core 
are  initialized  automatically  in  the  case  of  programs 
using  only  the  minimal  Nu-Speak  package,  and  hy  the  macro 
READY  which  must  be  the  first  instruction  of  any  program 
using  the  Nu-Speak  list  macros. 

B3.  Use  of  the  Nu-Speak  Macros  of  the  First  (Recursion) 

Group . 

Glendower:   I  can  call  spirits  from  the  vasty  deep. 
Hotspur:     Why  so  can  I,  or  so  can  any  man; 

But  will  they  come  when  you  do  call 
for  them? 

—  Henry  IV  -  Part  I. 

The  form  of  the  SUBR  macro  is 

SUBR   NAME, INPUTS, (LISTl) ,0UTPTS, (LIST 2) , (LIST^) 
where 

NAME   is  the  subroutine  name 

LISTl   is  the  list  of  dummy  inputs  (with  names 
normally  but  not  necessarily  less  than 
6  characters) 

LIST2   is  the  list  of  dummy  outputs  (with  names 

normally  but  not  neces .  less  than  6  char.) 

LIST3  is  a  list  of  registers  used  in  the  subroutine 
and  to  be  restored  on  exit.  Index  register  H- 
is  always  saved.  Index  register  N,  N  7^  4,  is 
specified  by  the  symbol  XN.   Q  specifies  that 
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the  MQ  is  to  be  saved;   I  the  sense 
indicators.   In  addition,  L  specifies  that 
all  the  list-involved  registers  are  to  be 
saved,  i.e.,  L  is  equivalent  to  X6,  X7,  I 
and  Q. 
If  a  subroutine  has  no  explicit  input  or  output 
variables,  the  corresponding  words  INPUTS  or  0UTPTS 
should  be  omitted.   LIST3,  too,  may  be  omitted  should 
the  saving  of  the  machine  registers  be  unnecessary. 

If  a  subroutine  uses  certain  arguments  internally 
and  if  these  arguments  do  not  remain  constant  during 
recursive  use  of  the  subroutine,  a  list  of  these 
arguments  should  appear  in  the  INTARS  macro 

INTARS     (List) 
within  the  SUBR .   At  most  one  use  of  the  INTARS  macro 
may  occur  in  any  SUBR . 

ArgiMients  not  logically  needed  in  a  recursion  may 
be  specified  by  any  of  the  usual  methods.   (INTARS  will 
work  Just  as  well  for  them,  but  will  waste  XEQ  time  and 
stack  space . ) 

Storage  will  automatically  be  provided  for  any  dummy 
variable  explicitly  designated  as  an  input,  output  or 
internal  argument  by  the  INTARS  macro,  see  below.   None 
of  these  variables  should  be  otherwise  defined  (in  the 
ordinary  FAP  sense),  or  the  assembly  will  fail  owing  to 
multiply  defined  symbols. 

THE  F0RTRAN  USER  IS  WARNED  that  a  subroutine  entered 
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by  the  macro  SUBR  will  bring  in  only  those  variables 
explicitly  designated  as  INPUTS  and  will  return  only 
those  variables  explicitly  designated  as  0UTPTS .   Thus, 
the  lines 

USE   PR0CES, (A,B),C 

SUBR  PR0CES, INPUTS, (A, B),0UTPTS, (C) 

CLA   A 

ADD  =1 

ST0   A 

•  •  • 

will  change  the  values  of  A  and  B  for  use  during  the 
execution  of  PROCES,  but  will  restore  them  to  their 
original  values  upon  executing  a  subsequent  RETFRM. 
Similarly,  the  line 

USE   PR0CES, (A,B),C 
followed  by 

SUBR    PR0CES , INTPUTS , ( A , B ) , 0UTPTS , ( C ) 

CLA    C 

*  •  • 

will  leave  PR0CES  operating  on  whatever  value  of  C  was 
left  stored  upon  the  last  RETFRM  PR0CES . 

Subroutine  names  can  be  inputs  to,  and  outputs 
from,  other  subroutines.  Just  as  in  FORTRAN  (and  in 
this  sense  operate  as  transfer  vectors).   The  following 
code  will  set  C  equal  to  the  value  obtained  by  applying 
a  function  called  PR0CES  30  times  iteratively  to  C. 
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USE 


ITERAT, (PR0CES,=3O,0),C 


BEGl 


ENDl 


SUBR 

D0BEG 

USE 

D0END 

PINI 


ITERAT, INPUTS, (PCN,N0,VAR ) ,0UTPTS, (VAL) 

Eiroi,l,  =  l,N0 

FCN,VAR,VAL 

BEG1,1 


the  above  lines  also  illustrate  the  use  of  the  do-loop 
pair  D0BEG  and  D0END,  which  is  described  more  carefully 
below. 

The  following  code  will  calculate  F(2),  P  being 
that  one  of  the  functions  PUNCl  and  FUNC2  for  which 
P(l)  assumes  the  larger  value, 

USE       SELECT, (PUNCl, FUNG 2), WINNER 

USE       WINNER, =2, RESULT 

SUBR  SELECT, INPUTS, (PR0C1,PR0C2) ,0UTPTS,BETTR 

USE  PR0C1,=1,VAL1 

USE  PR0C2,=1,VAL2 

INTARS  (VAL1,VAL2) 

CLA  VALl 

SUB  VAL 2 

TMI  2BETR 

CLA  PR0C1 
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2BETR 


ST0 

BETTR 

RETPRM 

SELECT 

CLA 

PR0C2 

ST0 

BETTR 

RETFRM 

SELECT 

FINI 

ETC  cards  can  be  used  to  extend  the  first  line  of  SUBR . 
THE  P0RTRAN  USER  IS  WARNED  that,  as  distinct  from 
the  F0RTRAN  word  SUBR0UTINE,  the  appearance  In  a  Nu-Speak 
program  of  the  word  SUBR  will  not  begin  a  new  program  (in 
the  sense  of  the  PAP  assembler) .   A  Nu-Speak  subprogram  is 
terminated   only  by  an  END  card,  and  begun  only  by  a  -^FAF 
card.   Thus  all  the  FAP  symbolic  code  belonging  to  the 
various  SUBR's  of  a  section  of  Nu-Speak  code  belongs  to 
a  single  FAP  program.   To  provide  proper  isolation  from 
each  other  of  variables  belonging  to  different  SUBR's, 
but  having  the  same  symbolic  names,  Nu-Speak  uses  a  heading 
scheme,  based  on  the  HEAD  pseudo-operation  in  FAP.   This 
mechanism  works  as  follows:   each  appearance  of  SUBR 
assembles  the  intermediate  macro  HEADER  (see  account  below) 
which  provides  a  heading  character  (the  same)  for  every 
symbolic  name  in  the  body  of  code  covered  by  the  SUBR. 
Thirty-five  heading  characters  are  Issued  in  the  order 
Z,Y,X, ...,A,9,8, ...,0 
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to  successive  SUBR's.   If  there  are  more  than  35  SUBR's 
in  a  program,  the  HEADER  mechanism  will  begin  again  from 
Z.   The  line  FINI,  which  should  normally  be  the  last 
line  of  each  SUBR,  assembles  simply  as  HEAD  0,  PAP  symbols 
with  head  0  being  the  same  as  unheaded  symbols. 

Since  FAP  symbols  are  at  most  6  characters  long, 
6  letter  symbols  will  not  be  headed,  and  will  therefore 
be  accessible  to  all  SUBR's.    The  use  of  the  same 
6-character  symbol  as  an  explicit  INPUT,  0UTPUT,  or  INTAR 
of  two  different  SUBR's  will  therefore  lead  to  multiply 
defined  symbols.   On  the  other  hand,  by  using  a  six  charac- 
ter symbol  as  a  variable  in  a  single  SUBR,  one  allows 
other  SUBR's  to  have  access  to  it,  and  this  possibility 
provides  what  is  in  effect  a  "named  common"  which  can 
replace  the  "numbered"  C0MM0N  of  the  F0RTRAN-FAP  system. 
However,  if  one  SUBR  accesses  and  changes  an  argument  of 
another  SUBR  in  this  way,  the  recursiveness  of  the  system 
may  be  spoiled.  (For  a  detailed  understanding  of  this 
point,  see  appendix  below,  or  listing  of  the  macros  SUBR 
and  SUBBDY. )    Thus,  the  heading  system  makes  it  advisable, 
as  a  matter  of  ordinary  practice,  to  name  subroutines  with 
six  letter  symbols  (so  that  they  may  be  USE-d  within  other 
SUBR's),  and  to  name  variables  and  other  locations  with 
symbols  of  five  characters  or  less. 

Programs  written  with  more  than  35  SUBR's  may 
inadvertently  produce  multiply  defined  symbols,  owing  to 
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the  re-use  of  heads.   In  the  (hopefully  few)  cases  In  which 
this  occurs,  it  can  be  cured  by  appropriately  renaming  the 
offending  variables  and  locations. 

The  macro  RETPRM  assembles  as  a  single  line  of 
machine  code,  e.g. 

RETPRM    PR0CES 
assembles  as 

TRA  '     PR0CES+5 

It  is  used  to  return  from  a  subroutine  to  the  calling 
routine,  and  is  analogous  in  function  to  the  F0RTRAN 
word  RETURN. 

The  macro  USE  assembles  the  same  lines  of  code,  and 
is  used  in  much  the  same  way,  as  the  FAP  pseudo-operation 
CALL,  but  with  the  exception  that  it  makes  no  transfer- 
vector  entry  (naturally  notl)-   Its  form  is 

USE      NAME, (LIS Tl), (LIST2) 
where 

NAME   is  the  name  of  the  subroutine  to  be  used 
LISTl   is  a  list  of  the  Inputs  provided  to  it  or 

the  word  N0INPS 
LIST2   is  a  list  of  the  outputs  which  it  is  to 
provide  or  the  word  N00UPS . 

The  variables  of  these  two  lists  must  coincide  in  number 
and  correspond  in  order  with  the  INPUTS  and  0UTPUTS 
declared  in  the  first  line  of  the  SUBR  named  NAME. 
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If  a  NU"Speak  SUBR  located  In  a  given  program  Is  to 
be  used  in  an  external  program,  it  should  be  called  in 
the  more  conventional  form 

CALL      NAME,LIST1,LIST2 
where  LISTl  is  a  list  of  input  arguments,  and  LIST2  is  a 
list  of  output  arguments.   In  addition,  the  first  card 
group  of  the  program  containing  the  SUBR  in  question  must 
contain  a  card  of  the  form 

ENTRY     NAME 
for  each  SUBR  which  is  to  be  used  by  an  outside  program. 

Since  the  assembly  of  the  m.acros  CALL  and  USE 
generate  a  line  of  the  form  TSX  SUBNAM,4  they  involve 
an  implicit  use  of  index  register  XR4,  and  hence  will 
change  its  contents.   In  order  that  the  contents  of 
XR4  may  be  restored  on  return  from  a  SUBR  if  desired, 
secondary  forms  CALSV4  and  USESV4  of  these  macros 
have  been  provided  ("call  saving  XR4"  and  "use  saving 
XR4").   These  act  in  just  the  sam.e  way  as  CALL 
and  USE,  except  that  XR4  is  stored  before  the  CALL 
' or  USE  and  restored  immediately  after  return  from  the 
SUBR.   Normal  Nu-Speak  practice,  however,  will  omit  those 
saves  and  restorations,  and  consider  the  value  of  XR4 
within  any  given  SUBR  to  be  indefinite.   The  proper 
"existing"  value  of  XR4  will  in  all  cases  be  saved  on 
entry  to  a  SUBR,  and  XR4  will  be  restored  to  its  initial 
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value  just  prior  to  a  return  from  the  SUBR .   (Cf.  the 
discussion  above  of  XR-save  specifications  in  a  SUBR 
head . ) 

The  DEBUG  feature  of  Nu-Speak  Is  controlled  by  a 
card  of  the  form 

DEBUG  blank,     or    0N,    or   0PP. 

The  appearance  of  a  DEBUG  0N  card  will  cause  the  assembly 
of  all  following  SUBR's,  up  to  the  next  DEBUG  0PP  or 
DEBUG  card,  to  be  modified.   As  a  consequence  of  this 
m_odification,  each  entry  into  the  SUBR  will  produce  a 
message  of  the  form  SUBR0UTINE  NAMED  (name  of  subroutine) 
HAS  JUST  BEEN  ENTERED,  together  with  a  statement  (in 
octal)  of  the  condition  of  the  accumulator,  P+Q  bits, 
MQ  register,  sense  indicators,  and  XR4  (complemented), 
and  input  arguments  while  each  subsequent  return  from 
the  SUBR  will  produce  a  message  of  the  form  SUBR0UTINE 
NAMED  (name  of  subroutine)  IS  BEING  LEFT,  together  with 
the  condition  of  the  same  principal  registers  as  above 
(excepting  XR4,  however),  and  a  statement  (in  octal)  of 
the  values  of  all  output  arguments.   The  DEBUG  0PP  card 
terminates  the  debug  feature;  alternate  appearances  of 
the  card  DEBUG  switch  this  feature  off  and  on.   While 
using  the  DEBUG  feature,  the  Nu-Speak  binary  deck  marked 
DEBUGPR0G  must  be  included  with  the  deck  being  loaded 
(see  below,  form  of  decks  for  Nu-Speak  jobs).   This 
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program  calls  in  the  4,000-odd  words  of  the  (I0H)  complex, 
and  so  may  reduce  the  amount  of  core  space  available  to  the 
new  program  complex  by  a  considerable  amount. 

When  the  debugging  of  a  Nu-Speak  program  is  complete, 
all  the  DEBUG  cards  may  be  removed  from  the  source  symbolic 
deck;  the  binary  DEBUG  PR0G  deck  is  to  be  removed  also. 
The  source  deck  will  then  assemble  into  final  form. 

The  macros  ARITH  and  ARITHA  provide  a  rudimentary 
set  of  floating  point  and  double-precision  floating  point 
arithmetic  macros.   Their  form  is 

ARITH   variable,  word,  (list),  equals,  variable  2 
and 

ARITHA  word,  (list),  equals,  variable  2. 
Here 

(a)  "word"  denotes  one  of  the  four  single-precision 
control  words  PLUS,  MINUS,  TIMES,  or  0VER,  with  obvious 
arithmetic  operational  significance,  or  one  of  the  four 
double-precision  control  words  DPLUS,  DMINUS,  DTIMES,  or 
D0VER,  of  corresponding  significance. 

(b)  "equals"  denotes  the  control  word  EQUALS,  which 
may  however  be  absent,  in  which  case  the  word  "variable  2" 
may  as  well  be  absent  also  (cf.  below). 

(c)  variable  2  is  the  symbolic  name  of  a  variable 
which  is  to  be  set  equal  to  the  result  of  the  preceding 
arithmetic  operations.   (If  this  variable,  together  with 
the  word  EQUALS,  are  omitted,  the  result  will  be  left  in 
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the  accumulator  (or  accumulator  and  MQ,  in  case  of 
double-precision  variables.) 

(d)  "list"  is  a  list  of  the  variables  to  be 
successively  combined  using  the  operation  specified 
by  "word." 

(e)  "variable"  in  the  ARITH  macro  is  the  variable 
to  be  brought  into  the  central  processing  unit  at  the 
start  of  the  desired  arithmetic  operations;  the  macro 
ARITHA  finds  its  first  variable  already  in  the  accumulator, 

The  use  of  ARITH  and  ARITHA  are  illustrated  in  the 
following  program,  which  has  the  same  effect  as  the 
F0RTRAN  statement   A-  (SQRTF(X*Y*Z*W-1 .0) )/Xl . 

ARITH  X,  TIMES,  (Y,Z,W) 

ARITHA  MINUS,  =1.0 

CALL  SORT 

ARITHA  0VER,  XI,  EQUALS,  A 

The  form  of  the  macro  FL0AT  is 

PL0AT     variable,  equals,  variable  2; 
the  form  of  the  macro  FL0ATA  is 

FL0ATA    equals,  variable  2. 

Here  "equals,"  and  "variable  2"  have  the  same  signifi- 
cance as  above  in  the  macros  ARITH  and  ARITHA,  and  may 
be  omitted  with  the  same  consequences  as  above. 
"Variable"  is  the  symbolic  name  of  the  full  word 
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(P0RTRAN  USERS  WARNED)  integer  to  be  converted  to  float- 
ing point.   The  macro  FL0ATA  finds  its  variable  in  the 
accumulator . 

The  do'loop  pair  D^BEG  (do-loop  beginning)  and 
D0END  (do-loop  ending)  have  the  following  form: 

location  1     D0BEG   location  2,  numb.  A,  B 
location  2     D0END   location  1,  numb 

Here  "location  1"  and  "location  2"  must  be  valid 
PAP  symbols  designating  the  location  of  the  beginning 
and  end  of  the  do-loop,  "numb"  is  an  integer  from  1  to 
7  designating  the  index  register  in  which  the  count 
for  the  do-loop  is  to  be  kept,  and  A  and  B  are  loca- 
tions ("variables")  whose  ADDRESS  P0RTI0NS  (P0RTRAN 
USERS  WARNED)  contain  respectively  the  lower  and  upper 
count  limits  for  the  do-loop. 

The  alternate  do-loop  pair  RD0BEG  (recursive  do- 
loop  beginning)  and  R0END  (recursive  do-loop  ending) 
have  exactly  the  same  form  and  much  the  same  use,  but 
are  more  suitable  in  certain  circumstances  for  use  in 
recursive  subroutines.  The  distinction  is  most  easily 
perceived  by  examining  the  expansion  of  these  macros. 
D0BEG  expands  as 
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START 


D0BEG 

END,  XR,  K,  L 

LXA 

L,XR 

SXD 

START, XR 

LXA 

K,XR 

TKH 

END+1,XR,** 

EKD 

START 
D0BEG 

while  the  expansion  of  the  D0ENT3  Is 

D0END     MACR0    START, XR 

TXI     START,  XR,1 
D0END      END 

If  a  recursive  subroutine  calls  Itself  (even  indirectly) 
from  within  such  a  do-loop,  the  decrement  in  the  instruc- 
tion START  will  be  changed,  and  the  do-loop  may  fail  to 
function  correctly  on  return  from  the  subroutine.   To 
protect  against  such  failure,  the  code 

CLA      START 

S,T0     VAR 
can  be  executed  Immediately  before  the  recursive  subrou- 
tine call,  and  the  code 

CLA     VAR 
ST0     START 

executed  immediately  after  returning  from  the  subroutine 
called  recursively;  here  VAR  should  be  one  of  the  INTAR's 
of  the  calling  subroutine. 
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To  avoid  this  nuisance,  the  alternate  do-loop  pair 
may  be  employed.   RD0BEG  expands  as 

RD0BEG     MACR0    END,XR,A,B 


LXA 

A,XR 

SOD 

*+5,XR 

SXD 

*+3,XR 

LXA 

B,XR 

TXI 

*+l,XR,l 

TXL 

END+1,XR,*^ 

TXI 

^+1,XR,** 

END 

RD0BEG 

and  RD0END  expands  as 

RD0END     MACR0    START, XR 

TIX      START+7,XR,1 
RD0END     END 

Since  the  cut  off  control  for  a  do-loop  of  this  type  is 
carried  in  an  index  register  which  will  be  saved  and 
restored  during  the  recursion  if  its  use  is  noted  in  the 
SUBR  header,  such  a  do-loop  will  function  properly  even 
in  the  above-described  recursive  situation. 

To  illustrate  the  use  of  these  macros,  we  give  the 
following  lines  of  code,  which  will  store  1,000  times 
the  variable  B  in  the  variable  C,  and  incidentally, 
leave  index  register  1  set  at  1,001) : 
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CLA  =1000 

ST0  C0UNT 

FL0AT  =0,  EQUALS,  B 

HERE      D0BEG  THERE, 1,=1, C0UNT 

ARITH  B, PLUS, C, EQUALS, C 

THERE     D0EKD  HERE,1 

•  •  • 

Much  the  same  code  could  be  written  more  simply  as 

PL0AT  =0, EQUALS, B 

WHENS      D0BEG  WITHR, 1,=1,=1000 

ARITH  B, PLUS, C, EQUALS, C 

WITHR      D0END  WHENS, 1 

If  the  upper  limit  of  such  a  do-loop  lies  below 
its  lower  limit,  it  will  not  be  executed  at  all. 

Pairs  of  D0BEG's  and  D0ENI) '  s  using  different  index 
registers  may  be  nested  within  each  other  in  obvious 
fashion. 

The  user  is  warned  that  the  location  symbol  written 
in  the  location  field  of  a  D0BEG  macro-operation  does  not 
describe  the  location  of  the  first  line  of  generated  machine 
code.   For  a  detailed  understanding  of  the  point,  a  listing 
of  the  D0BEG  macro  should  be  consulted. 

The  programmer  wishing  to  obtain  an  automatic  dump 
when  freespace  becomes  exhausted  in  a  program  using  only 
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the  minimal  Nu-Speak  package  may  Include  the  control  card 
ALDUMP  as  the  first  instruction  of  his  program.   (WARNING: 
a  6ump   produced  in  these  circumstances  will  normally  be 
approximately  200  pages  long.)   The  four  macros  BEGSTK, 
PUTIN,  TAKFRM,  and  CNTSTK  enable  the  user  to  automatically 
construct  and  use  any  number  of  "LAST  IN/FIRST  0UT"  type 
push  down  stacks. 

The  macro  BEGSTK  has  the  form 

BEGSTK         slze,wd,loc 
where  size  is  a  decimal  integer  equal  to  the  number  of  core 
locations  to  be  reserved  for  the  operation  of  the  stack. 

This  defines  the  size  of  the  stack,  and  provides 
either  for  the  production  of  an  error  message  or  for  a 
specific  transfer  of  control  on  stack  overflow  or  underflow. 

A  stack  of  nominal  size  N  will  actually  occupy  N+4  core 
locations . 

If  the  macro  is  used  without  the  last  2  words,  wd  and 
size,  as  e.g.  in 

STACKl    BEGSTK    5OO 
an  error  message  and  termination  of  execution  will  result 
on  stack  overflow  or  underflow.   If  the  macrovariable  is 
replaced  by  the  control  word  RETURN,  as  in 

STACKl    BEGSTK    5OO, RETURN, L0CL 
return  on  overflow  or  underflow  will  be  made  to  the 
program  location  L0CL. 

If  the  programmer  desires  to  return  control  after 
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the  stack  has  been  filled  or  emptied  to  some  point 
designated  by  himself  (by  using  the  long  form  of  the 
BEGSTK  macro  Instruction) ^  he  will  probably  want  one 
set  of  Instructions  to  be  executed  after  the  stack  has 
been  filled,  and  another  after  It  has  been  emptied. 

In  the  case  of  stack  underflow  or  overflow  control 
will  always  be  transferred  to  the  location  specified  by 
the  user  In  his  BEGSTK  statement.   (If  no  return  location 
Is  specified,  stack  underflow  or  overflow  will  pr'oduce  an 
error  message  and  program  termination.)   If,  when  the 
CPU  arrives  at  the  specified  location,  XRl  contains  0, 
a  stack  underflow  condition  exists.   If  XRl  contains 
-SIZE-2,  a  stack  overflow  exists.   It  is  suggested  that 
the  instruction  at  location  L0CL  be: 

L0GL       TXL        EMPTY, 1,0 

EMPTY 

Since  -SIZE-2  is  stored  in  XRl  as  a  positive  number 
(the  2's  complement)  control  will  then  pass  to  one  set  of 
statements  after  the  stack  has  been  emptied  (XRl  =  0) 
and  to  another  set  of  statements  after  the  stack  has 
been  filled  (XRl  =  -SIZE-2). 

Note  that  XRl  may  be  used  within  the  program  since 
it  Is  saved  and  restored  by  the  stack  macros. 

BEGSTK  must  be  placed  in  a  portion  of  the  program  to 
which  control  can  never  pass  (e.g.  after  a  CALL  EXIT  state- 
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ment) .      Control  will  then  only  pass  to  it  via  the  PUTIN 
or  TAKPRM  macros.   Also  there  must  be  a  symbol  in  the 
location  field  of  the  macro-instruction.   This  is  the  name 
of  the  stack  and  is  defined  as  the  location  of  the  first 
machine  instruction  in  the  macro.   It  must  not  be  omitted. 
The  form  of  the  macro  PUTIN  is 

PUTIN  A 

where  A  is  the  name  of  a  stack  created  by" the  macro 
BEGSTK.   It  stored  the  contents  of  the  accumulator  in 
successive  locations  of  the  stack  A.   The  inverse 
operation  is  performed  by  the  macro  TAKPRM  which  has 
the  corresponding  form. 

TAKPRM         A 

PUTIN  MYSTAK 

CALL  EXIT 

MYSTAK    BEGSTK  500 

A         BEGSTK  28 

The  first  element  PUTIN  a  stack  is  always  the  last 
element  TAKen  FRM  the  stack. 

Both  PUTIN  and  TAKERM  work  must  more  rapidly  (12 
cycles)  than  the  corresponding  list  macros  INSERT  and 
REM0VE,  and  should  be  used  in  preference  to  the  list 
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macros  where  the  additional  flexibility  and  logical 
connections  of  the  list  macros  are  unnecessary. 

The  final  macro  of  the  Nu-Speak  pushdown-stack 
set  is  CNTSTK,  which  has  the  form 

CNTSTK  NAM,SIZE,RMNING. 

Here  NAM  is  the  name  of  a  stack,  SIZE  is  its  size,  and 
RMNING  is  a  core  location.   Use  of  this  macro  will  store 
the  number  of  locations  remaining  in  the  stack  in  the 
address  of  the  location  RMNING. 

b4.   The  Second  (String -Manipulation)  Set  of  Nu-Speak 
Macros . 

To  understand  the  use  of  the  Nu-Speak  list-processes, 
it  is  necessary  to  understand  something  of  the  Nu-Speak 
representation  of  lists  within  the  709^-   Lists  are 
constructed  out  of  three  t;^TDes  of  elements:   data 
elements,  llstheads,  and  links. 

(a)   Data  elements.   Data  elements  are  stored  in 
core  in  blocks,  always  containing  an  even  number  from  2-l6 
of  successive  core  words,  and  always  beginning  at  an  even 
core  location.   The  first  word  of  a  block  is  its  identifier; 
the  remaining  words  represent  successive  data  items  on  a 
list.   The  structure  of  the  identifier  is  as  follows 


ioi 

prev 

T 

next 

S  1  2  3         17  18  20  23       35 
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where 

(al)  "next"  denotes  the  address  of  the  identifier  of 
the  next  block  in  the  list;  the  NEXT  of  the  last  identifier 
in  a  string  points  back  to  the  head  of  the  string  (see  below). 

(a2)  "prev"  denotes  the  address  of  the  identifier  of  the 
previous  block  in  the  listj 

(a3)  T  is  an  octal  integer  between  0  and  7  representing 
the  number  of  words  in  the  block  according  to  the  convention 
no  +  2(T+1); 

(a4)  The  prefix  01  (with  Indeterminate  sign  bit) 
indicates  that  the  block  v\fhich  follows  is  data  (rather 
than  a  head  or  a  link) . 

(b)  Head  elements.   A  head  element  is  stored  in  a 
block  of  two  words  consisting  of  an  even  location  and  the 
next  successive  odd  location.   The  first  word  of  this 
block  is  the  head  identifier,  and  has  the  form 


1 

1  1 

prev 

0  0  0 

next 

S  1  2  3         17  18   20  21       35 
Here,  prev  and  next  have  the  same  significance  as  above, 

while  the  prefix  11  (with  indeterminate  sign  bit)  indi- 
cates that  the  blank  which  follows  is  a  head.  The  prev  of 
a  head  points  to  the  last  identifier  in  the  string. 

The  second  of  the  two  words  constituting  a  head  has 
the  form 


refns 


S  1 


20   21 
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here  refns  is  the  n\imber  of  current  references  to  the  list 
(see  below),  while  bits  S-20  are  unaffected  by  any  of  the 
built  in  Nu-Speak  list  macros  (see,  however,  the  account 
below  of  special  procedures  affecting  self-referent  lists) 
and  are  available  for  use  by  the  programmer. 

A  list  contains  one  and  only  one  head. 

(c)  Link  elements.   Link  elements  are  pointers  to 
sublists;  since  strings  are  distinguished  from  more  general 
lists  by  having  no  sublists,  we  postpone  a  discussion  of 
the  structure  and  function  of  these  elements  to  the  next 
section.   Here,  however,  we  shall  note  that  a  link,  like 
a  head,  occupies  a  pair  of  locations,  the  first  being  even; 
and  that  the  first  word  of  the  pair  is  the  link  identifier. 

The  computer  is  said  to  be  "looking  at"  an  element  of 
a  list  (data  item,  head,  or,  for  that  matter,  link)  if 

1.    A  copy  of  the  identifier  of  the  block  in  which 
the  element  lies  is  in  the  sense  indicator  register  SI; 

ii.   The  address  of  the  identifier  of  the  head  of 
the  list  containing  the  element  is  contained  in  comple- 
mented form  in  the  index  register  X6; 

iii.  An  integer  from  1  to  I5,  and  denoting  the 
position  of  the  data  word  within  its  block  is  contained 
in  the  index  register  XT; 

iv.   A  copy  of  the  data  word  concerned  (or,  in  the 
case  of  heads  (or  links,  cf.  next  section),  the  odd- 
location  word  following  the  identifier)  is  contained  in 
the  MQ  register. 

-   51   - 


With  this  understanding,  we  may  proceed  to  explain  the 
effect  of  the  Nu-Speak  list  macros  of  the  string-manipula- 
tion group . 

The  macros  NEXT  and  PREV  have  the  form 

NEXT 
and 

PREV 

respectively.   If  the  computer  is  looking  at  an  element  of 
a  list  (whether  head,  data,  or  link)  these  macros  cause  it 
to  look  at  the  next  and  the  previous  elements  respectively. 
The  macro  CUPL  has  the  form 

CUPL        listname, 

where  listname  is  the  symbolic  name  of  a  certain  list. 
If  the  computer  is  looking  at  an  element  on  a  list  when  this 
macro  is  encountered,  it  will  couple  the  list  named  "list- 
name"  into  the  list  containing  the  element  being  examined; 
that  is,  transform  the  list  being  examined  by  insertion  of 
all  data  items  and  links  of  the  list  named  "listname,"  the 
insertion  beginning  immediately  after  the  data  item  origi- 
nally being  examined.   The  inserted  items  then  precede  the 
item  originally  following  the  item  at  which  the  computer 
was  looking.   The  computer  is  left  looking  at  the  same 

element . 

The  list  "listname"  being  coupled  loses  its  separate 
identity  in  this  process,  and  its  head  is  erased  and  returned 
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to  a  pile  of  spare  head  locations.   Thus,  for  example,  if 
two  lists,  named  LISTl  and  LIST2  are  contained  in  core, 
if  LISTl  contains,  besides  its  head,  the  3  data 
ALPHA,  BETA,  and  GAMMA,  and  if  LIST2  contains,  besides 
its  head,  the  3  data   HEE,  HAW,  H00,   then,  if  the 
computer  encounters  the  macro 

CUPL    LIST2 

while  looking  at  the  datum  ALPHA  on  LISTl,  the  result 
will  be  that  LISTl  will  come  to  have  the  six  data 
ALPHA,  HEE,  HAW,  H00,  BETA,  GAMMA,  and  LIST2  will  have 
ceased  to  exist.   The  computer  will  be  left  looking  at 
ALPHA.   On  the  other  hand,  the  lines 

PREV 

CUPL    LIST2 

will  produce  a  LISTl  containing  the  six  data  HEE,  HAW, 
H00,  ALPHA,  BETA,  GAMMA;  LIST2  will  again  have  ceased 
to  exist.   The  computer  will  be  left  looking  at  the  head 
of  LISTl. 

The  macros  INSERT  and  REM0VE  have  the  form 

INSERT      variable, 
and 

REM0VE 

where  "variable"  is  the  symbolic  name  of  a  variable.   If 
the  computer  is  looking  at  a  data  item  or  link,  REM0VE 
will  cause  this  item  to  be  properly  deleted  from  the  list, 
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and  will  leave  the  computer  looking  at  the  next  element 
of  the  list.  An  attempt  to  delete  a  head  will  cause  an 
error  return. 

If  the  computer  is  looking  at  a  list  item,  "INSERT 
variable"  will  cause  the  contents  of  location  named 
variable  to  be  Inserted  In  the  list  immediately  follow- 
ing the  said  item,  and  will  leave  the  computer  looking 
at  the  inserted  item. 

The  macros  NAMLIS  and  'CLERNM  have  the  form 
NAMLIS      list name, 
and 

CLERNM      listname 

respectively,  where  "listname"  is  the  symbolic  name  of 
a  variable  which,  in  the  first  case,  is  to  become  the 
name  of  a  list,  and,  in  the  second,  is  to  cease  being 
the  name  of  a  list. 

It  should  be  said  here  that  the  name  of  a  list  is, 
in  machine  terms,  a  storage  location  whose  address  part 
contains  the  address  of  the  identifier  word  of  the  head 
of  the  list. 

The  significance  of  the  last  two  macros,  and 
especially  of  CLERNM,  may  be  further  elucidated,  as 
follows.   As  Nu-Speak  list  processing  proceeds,  a 
running  account  of  the  number  of  references  to  a  list 
is  automatically  kept  in  21-55  of  the  second  word  of 
the  listhead.   (If  this  number  exceeds  J>2,j67,    trouble 
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will  ensue) .   This  number  of  references  Is  determined  as 
the  total  of  all  the  names  of  the  list,  (plus  all  the  links 
pointing  to  the  listhead,  that  is  the  number  of  times  the 
list  occurs  as  a  sublist,  as  explained  in  Section  5 
below) .   Whenever  the  number  of  references  to  a  list 
is  reduced  to  zero,  the  list  will  automatically  be  erased. 
Care  should  therefore  be  taken  not  to  disturb  the  count 
of  references  to  a  list  inadvertently. 

The  macro  "NAMLIS  llstname"  increases  the  reference- 
count  of  the  list,  an  element  of  which  is  currently  being 
looked  at,  by  1,  and  delivers  the  address  of  its  head  to 
the  location  "llstname."   In  this  way,  "llstname"  becomes 
a  name  of  the  said  list. 

The  macro  "CLERNM  llstname"  reduces  the  number  of 
references  to  the  list  named  "llstname"  by  1 .   It  leaves 
the  MQ  and  SI  registers,  and  the  index  registers  of  the 
central  processor  unaltered. 

The  macro  JUMPT0  has  the  form 

JimPT0  llstname 

where  "llstname"  is  the  name  of  a  list;  and  acts  as 
follows:   if  the  central  processor  is  looking  at  an 
element  on  a  certain  list  when  it  encounters  the  instruc- 
tion JIMPT0  llstname,  then  the  central  processor  will  be 
left  looking  at  the  head  of  the  list  named  "llstname". 

The  two  test  operations  TEHEAD  and  TEDATA  cause 
"skips"  like  the  standard  PAP  "test-type"  orders,  and  have 

-  55  - 


the  following  effect:   if  the  central  processor  is  looking 
at  a  list  element,  then  TEDATA  will  cause  the  next  machine 
instruction  (WARNING:   N0T  MACR0  INSTRUCTI0N)  to  be  skipped 
if  this  list  element  is  data;  if  the  list  element  being 
looked  at  is  not  data,  the  control  processor  will  execute 
the  next  instruction.   TEHEAD  operates  similarly,  causing 
the  central  processor  to  skip  the  next  machine  instruction 
if  the  central  processor  is  looking  at  a  head,  but  to 
execute  the  next  machine  instruction  if  the  central  proces- 
sor is  not  looking  at  a  head.   These  instructions  should 
be  used  only  when  it  is  known  that  the  central  processor 
is  looking  at  some  element  on  some  list,  as  they  may 
otherwise  result  in  unaccountable  skips. 

The  Nu-Speak  macro  CREATE  has  the  form 

CREATE      listnarae 

where  "listname"  is  the  name  of  a  variable.   This  macro 
creates  a  list  with  no  entries  (and  hence  consisting 
exclusively  of  a  head  which  is  its  own  NEXT  and  PREV), 
and  stores  the  address  of  the  identifier  of  this  head 
in  the  variable  "listname,"  so  that  the  variable  becomes 
the  name  of  the  nullist.   The  central  processor  is  left 
looking  at  the  head  of  the  newly  created  list.   This 
macro  can  be  used  even  at  a  point  in  a  program  where 
the  central  processor  is  not  looking  at  any  list  element. 

If  the  central  processor  is  examining  an  item  on  a 
list,  the  macro  NCPLT0,  which  has  the  form 
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NCPLT0      variable 

will  break  the  list  immediately  after  the  item  being  examined 
removing  from  the  list  all  items  from  this  point  on  and  up  to 
but  not  including  its  head  (which  is  both  first  and  last  item 
on  every  list).   A  new  list  will  be  formed^  consisting  of 
the  items  deleted,  and  having  the  name  "variable."   The 
central  processor  is  left  looking  at  the  head  of  the  newly 
formed  list.   Thus,  e.g.,  if  the  central  processor  encoun- 
ters the  instruction 

NCPLT0      LISTl 

while  looking  at  the  item  ALPHA  on  a  list  named  LIST2  whose 
entries  are  ALPHA,  BETA,  GAMMA,  LIST2  will  be  reduced  to 
the  single  entry  ALPHA,  while  LISTl  will  have  the  entries 
BETA,  GAMMA.   In  the  same  situation,  the  lines 

PRE7 

NGPLT0       LISTl 

will  leave  LIST2  as  a  list  without  any  entries  (consisting 
only  of  a  head)  and  LISTl  will  have  the  entries  ALPHA,  BETA, 
GAMMA.   Again  in  the  same  situation,  on  using  the  lines, 

PREV 
PREV 
NCPLT0      LISTl 

the  list  LIST2  will  retain  the  entries  ALPHA,  BETA,  and 
GAMMA,  and  LISTl  will  have  no  entries. 
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The  macro  C0PYT0  has  the  form 

C0PYT0         listname 
where  "listname"  Is  a  PAP  variable,  that  Is  a  FAP 
location.   If  the  central  processor  Is  not  looking  at 
a  llsthead  when  It  encounters  this  Instruction,  an 
error  message  will  result,  and  execution  will  be 
terminated.   On  the  other  hand.  If  "C0PYT0  listname" 
Is  encountered  when  the  central  processor  Is  looking  at 
the  head  of  a  list,  a  copy  of  the  list,  with  all  data 
Items  and  links  Included  will  be  produced,  and  the  newly 
produced  list  will  be  named  "listname."   The  central 
processor  will  be  left  looking  at  the  head  of  the 
original  list,  with  the  second  word  of  the  original 
llsthead  in  its  MQ.   (The  arrangement  of  data  words 
within  blocks  of  core  is  not  necessarily  the  same  in 
the  copy  as  in  the  original  list,  however.) 

The  pair  of  macros  ERASER  and  ERAS0R  have  the  form 

ERASER 
and 

ERAS0R 
respectively.   Both  of  these  instructions  may  be  used 
when  the  address  of  a  llsthead  identifier  is  contained 
in  the  address  portion  of  the  accumulator;  either  will 
then  proceed  to  erase  the  list  in  question  by  attaching 
to  it  the  bottom  of  a  special  "Junkplle  list"  of 
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elements  available  for  re-use.   (See  Section  5A  for  a 
more  detailed  account  of  the  Internal  procedures 
Involved.)   ERASER  tests  the  location  concerned  to 
verify  that  It  contains  a  llsthead  and  provides  an 
error  return  If  an  error  Is  detected;  ERAS0R  omits 
this  test.   ERASER  should  therefore  normally  be 
preferred . 

The  macros  RELEAS  has  the  form 

RELEAS  A,B 

the  macro  will  form  a  headless  string  of  B  words 
beginning  with  location  A  and  extending  upward 
through  consecutive  core  locations.   This  headless 
string  will  then  be  attached  to  the  top  of  the 
freespace  Junkplle  (see  below).   Thus,  B  core  loca- 
tions, beginning  with  location  A,  are  in  effect 
"released"  for  future  reassignment  by  the  FREESP 
macro.   Since  a  data  identifier  will  be  Inserted 
in  A,  A  must  be  an  even  location.   If  odd,  A  will 
be  Increased  by  1  and  B  will  be  decreased  by  1, 
Care  must  be  taken  not  to  RELEAS  the  same  block  of 
core  twice  unless  that  block  has  completely  been 
reassigned  by  FREESP. 
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The  macro-instruction  READY  should  be  the  first 
Instruction  In  any  Nu-Speak  program  using  any  of  the 
(other)  list  macros.   It  Initializes  various  counters 
and  pointers  In  the  basic  Nu-Speak  programs,  thus 
preparing  for  the  list  processing  operations  which  are 
to  follow.   This  macro  also  provides  the  programmer 
with  control  over  the  Nu-Speak  automatic  dump  procedures, 
which  are  as  follows: 

(a)  If  any  one  of  a  number  of  detectable  errors 
(e.g.,  attempting  to  delete  the  head  of  a  list,  begin- 
ning to  copy  a  list  at  a  position  other  than  Its  head, 
etc.)  occurs  In  a  Nu-Speak  program,  execution  will  be 
terminated,  an  appropriate  error  message  will  be  produced, 
and  a  core  dump  In  octal  with  mnemonics  will  be  given 
automatically  before  EXIT  is  called. 

(b)  If  the  generation  of  lists  or  the  growth  of 
the  pushdown  list  exhausts  all  available  freespace, 
execution  will  be  terminated,  and  message  to  this 
effect  will  be  produced,  but  no  dump  will  be  given. 

To  suppress  the  dump  that  would  otherwise  be 
produced  In  case  (a),  the  READY  card  should  have  the 
form 

READY       N0DUMP 

To  give  a  dump  in  case  (b),  the  ready  card  should 
have  the  form 

READY       ALDUMP 
-   60   - 


(WARNING:   a  dump  produced  when  freespace  is  exhausted 
will  normally  be  200  PAGES  LONG.) 

The  program  (FPT),  which  provides  for  automatic 
recovery  from  situations  of  floating  point  overflow  or 
underflow,  is  automatically  called  in  by  an  Nu-Speak 
program. 

The  auxiliary  list  macro  TESTBL  (test  and  break 
block  if  necessary)  has  the  form 

TESTBL 

If  this  command  is  received  while  the  processor  is 
looking  at  a  list  element,  it  will  check  to  see  if  the 
element  is  a  data  element  embedded  in  a  block  of  data 
elements  of  length  longer  than  1.   If  this  is  the  case, 
the  computer  will  proceed  to  break  the  block  (normally 
into  three  segments)  in  such  a  way  that  the  data  element 
concerned  becomes  the  end  of  the  subblock  containing  it. 
After  the  block  is  thus  broken,  insertions,  etc.,  can  be 
made  in  normal  fashion.   The  computer  is  left  by  TESTBL 
looking  at  the  same  list  element  as  previously,  (and  with 
the  data  word  of  this  element  brought  back  into  the  MQ) . 

The  following  precautions  are  to  be  observed  when 
using  list  processes  and  the  SUBR  and  related  macros 
together. 

a.   All  the  list  processes  make  use  of  index 
registers  XR6  and  XR7,  as  well  as  the  sense  indicator 
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register  SI  (and  naturally  the  accumulator  and  MQ) .   Thus 
a  list-processing  SUBR  will  effect  these  registers.   The 
Index  register  XR6  and  XR7  will  be  restored  to  their 
entering  condition  if  the  symbols  X6  and  XT  or  the  letter  L 
is  included  among  the  declared  XR's  in  the  normal  SUBR 
heading.   Similarly  the  sense  indicators  and  MQ  register 
will  be  saved  if  Q  or  L  is  specified  in  this  heading. 

All  of  the  list  operations  of  the  present  group  will 
function  properly  even  when  the  contents  of  the  MQ  (i.e., 
data  word;,  or  second  word  of  a  list  head)  have  been 
destroyed  by  processing  or  testing.   Thus 

NEXT 
and 

LDQ     =0 

NEXT 
have  precisely  the  same  result,  etc. 

All  the  Nu-Speak  list-macros  which  have  variable 
location  addresses  as  sole  arguments  obtain  these  arguments 
from  the  first  line  of  the  macro-generated  machine  code. 
Thus,  to  obtain  the  effect  of 

JTJMPT0      llstname 
but  with  a  more  easily  variable  "listname,"  lines  like 

CLA     listname 

STA     *+l 

JUMPT0      ** 
are  permissible. 
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The  arguments,  however,  may  not  he  tagged,  nor  may 
tags  be  stored  into  the  macros  in  a  manner  similar  to 
the  above. 

B5.   The  Nu-Speak  Macros  of  the  Third  (Sublist  Manipulat- 
ing) Group. 

Sublists  are  introduced  into  Nu-Speak  lists  by  insert- 
ing into  a  main  list  "links"  which  point  to  a  sublist.   A 
link  always  occupies  two  successive  words  in  core,  the  first 
in  an  even  location.   The  first  word  of  a  link  is  its 
identifier,  and  has  the  following  structure 


^ 

•  0   0 

prev 

0   0   0 

next 

S   12  3 


17  1^ 


20   21 


35 


where  "prev"  and  "next"  have  the  same  significance  as  above 
(cf.  the  first  paragraph  of  Section  4  above). 
The  second  word  of  a  link  has  the  form 


~ 

pointer 

20  21 


55 


where  "pointer"  is  the  address  of  the  identifier  of  the  head  of 
some  other  list.   Bits  S~20  are  unaffected  by  any  of  the 
Nu-Speak  processes,  and  are  available  to  the  programmer 
(as,  e.g.,  for  storing  various  bits  descriptive  of  the 
sublist) . 

All  the  above-described  macros  of  the  string  manipula- 
tion group,  with  the  obvious  exception  of  TEDATA,  treat 
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links  In  exactly  the  same  way  as  a  data  item  of  a  list. 

The  macro  TELINK  operates  as  follows.   If  the  central 
processor  is  looking  at  a  list  element  when  It  encounters 
TELINK,  It  will  skip  the  next  machine  instruction  if  the 
data  item  is  not  a  link.   The  macro  TELINK  should  not  be 
used  if  the  central  processor  is  not  looking  at  a  list 
entry,  as  it  may  lead  to  unaccountable  skips. 

The  macro  HANG  has  the  form 

HANG        llstname 
where  "llstname"  is  the  name  of  a  list.   Its  effect  is 
as  follows .   If  the  central  processor  is  looking  at  an 
item  on  a  list  when  It  encounters  HANG  llstname,  it  will 
insert  a  link  immediately  after  the  item  at  which  it  is 
looking.   The  second  word  of  this  link  will  contain  21 
leading  zeros,  followed  by  the  address  of  the  identifier 
of  the  list  named  "llstname;"  thus  the  link  will  "point" 
at  the  list  named  "llstname."   In  this  way,  the  list 
named  "llstname"  becomes  a  "sublist"  of  the  original 
list.   The  number  of  references  to  "llstname"  as 
enumerated  in  the  head  of  the  list  named  "llstname," 
is  augmented  by  1,     The  central  processor  is  left 
looking  at  the  newly  Inserted  link. 

Thus,  if  we  use  circles  to  denote  data  items,  squares 
to  denote  listheads,  and  rhomboids  to  denote  links,  the 
structure  of  a  typical  system  of  Nu-Speak  lists  might  be 
graphically  represented  by  a  structure  something  like  the 
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following; 


It  is  even  possible  that  a  subllst,  say  LIST2,  of  a 
certain  list,  say  LISTl,  should  Itself  have  LISTl  as  a 
subllst,  or  even  that  LISTl  should  be  a  subllst  of 
Itself,  a  situation  represented  graphically  by  the 
fdllQ--wing  dlagpam    ■  ;,".  ,-.-•;. 
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If  a  list  structure  is  such  that  its  lists  may  be 
arranged  in  an  ordered  hierarchy,  in  such  a  way  that  no 
list  has  either  itself  or  any  list  higher  in  the  hierarchy 
as  a  suhlist,  the  structure  is  said  to  be  non-reflexive j 
otherwise^  it  is  said  to  be  reflexive.   The  proper  treat- 
ment of  reflexive  list  structures,  especially  insofar  as 
erasing  and  procedures  which  lead  to  the  erasure  of  lists 
are  concerned,  is  logically  complicated  and  must  involve 
the  use  of  special  subroutines.   The  programmer  anticipat- 
ing the  development  of  such  list  structures  should  consult 
the  special  section  below  concerned  with  reflexive  list 
structures . 

The  inverse  operation  to  HANG  is  provided  by  the 
macro  UNHANG,  which  has  the  form 

UNHANG 
If  this  instruction  is  encountered  while  the  central 
processor  is  looking  at  a  list  item  which  is  not  a  link, 
an  error  return  will  be  produced,  and  execution  terminated. 
If  the  instruction  is  encountered  while  the  central  proces- 
sor is  looking  at  a  link,  then 

i)  the  link  will  be  deleted; 
ii)  the  numbev   of  references  to  the  sublist  to  which 
the  deleted  link  pointed  will  be  diminished  by  1; 
Hi)  if  no  references  to  the  aforesaid  sublist  remain, 
the  sublist  will  AUTOMATICALLY  BE  ERASEDj 
iv)  the  central  processor  will  be  left  looking  at 
the  next  item  on  the  list  which  had  previously 
contained  the  said  link^. 


Access  from  lists  to  subllsts  is  provided  by  the  macro 
SUBLIS,  which  has  the  form 

SUBLIS 
If  this  instruction  is  encountered  while  the  central 
processor  is  looking  at  a  list  item  which  is  not  a  link, 
an  error  message  will  be  produced,  and  execution  terminated. 
If  the  macro-instruction  is  encountered  while  the  central 
processor  is  looking  at  a  link,  the  instruction  SUBLIS  will 
leave  the  central  processor  looking  at  the  head  of  the 
sublist  to  which  the  link  points, 

b6.   Principles  of  Operation  of  the  Automatic  Erasing 
Mechanisms . 

When  a  list  is  erased  it  is  placed  at  the  bottom  of 
a  list  of  released  space  ("junkpile  list"). 

Whenever  one  of  the  Nu-Speak  list  macros  (e.g. 
INSERT,  C0PYT0)  requires  a  pair  of  free  spaces  for  the 
formation  of  a  new  list  element,  an  element  is  supplied, 
either  from  the  topmost  list  on  the  Junkpile,  or  from 
hitherto  unused  regions  of  core.   Conversely,  whenever 
space  is  released  (e.g,  by  ERASER,  RELEAS   or  REM0VE) 
it  is  automatically  added  to  the  junkpile.   Heads  are 
treated  similarly,  but  have  their  own  junkpile,  cf . 
below,  however. 

As  the  progressive  release  of  freespace  proceeds, 

links  pointing  to  sublists  may  be  encountered  in  erased 

lists.   In  each  such  case,  the  number  of  references  to 
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the  indicated  sublist  is  reduced  by  1.   If  the  number  of 
references  thereby  falls  to  zero,  the  sublist  is  itself 
erased,  and  placed  on  the  bottom  of  the  junkpile  list. 
When  the  freespace  mechanism  encounters  the  head  of  a 
list  on  the  ordinary  junkpile,  it  transfers  it  to  the 
head  junkpile. 

The  macro  DSTR0y  has  the  form 
'DSTR0Y 
Its  effect  is  as  follows.   If  the  address  portion  of  the 
accumulator  contains  the  address  of  a  listhead  identifier, 
the  prefix  of  the  identifier  will  be  changed  from  the 
normal   [^  1  1  |   to  the  special   |^  1  0  | ,   and  the 


list  erased  by  attaching  it  to  the  bottom  of  the  junk" 
pile  in  the  ordinary  way.   The  marking  of  a  list  in  this 
way  has  the  consequence  that  when  the  mechanism  for 
progressive  release  of  freespace  subsequently  reaches  a 
link  in  the  marked  list,  pointing  to  one  of  its  sublists, 
this  sublist  will  automatically  be  erased,  irrespective 
of  the  number  of  references  to  it.   However,  it  also  will 
inherit  the  prefixed  "mark  of  Cain"   j;^  1  0  |  ,  so  that 
sub=subllsts,  etc.,  will  be  treated  in  the  same  way. 
Thus,  by  using  DSTR0Y,  an  entire  list  structure  can  be 
erased  with  a  single  command. 

Note  however  that,  as  the  above  description  of  the 
operation  of  the  underlying  Nu-Speak  mechanisms  should 
make  plain,  it  is  always  fatal  to  erase  a  sublist  of  a 


list  before  the  main  list  Is  erased.   Indeed,  In  this 
case,  an  irrelevant  link  Is  left  in  the  main  list,  and 
if,  e.g.,  the  main  list  is  subsequently  erased,  the 
consequence  will  be  that  when  this  link  is  reached  by 
the  freespace  providing  mechanism,  a  change,  quite 
unanticipated  by  the  programmer,  will  be  made  at  the 
location  to  which  this  link  points,  and  at  various 
related  locations.      One  such  error  can  easily 
suffice  to  disrupt  everything. 

Thus  the  macro  DSTR0Y  should  be  used  cautiously, 
and  only  to  erase  the  lists  of  a  list  structure  which 
is  known  to  have  the  property  that  each  of  its  sub= 
lists,  sub-sublists,  etc.,  hangs  from  only  one  link, 
so  that  each  of  these  sublists,  sub-sublists,  etc., 
which  has  a  number  of  references  larger  than  1  has 
this  number  only  because  it  has  been  given  one  or  more 
names . 

In  such  situations  "DSTR0Y"  can  be  useful,  in  that 
it  can  spare  the  programmer  the  necessity  of  repeatedly 
using  "CLERNM"  in  order  to  erase  the  whole  structure 
with  a  single  command. 

A  special  routine,  REGLAR  (regularize  lists)  will 
be  made  available  at  a  date  in  the  near  future.   This 
routine  will  process  and  rearrange  the  core  storage  of 
all  the  data  stored  on  any  Nu-Speak  list,  compressing 
as  much  of  it  as  possible  into  I5  word  data  blocks,  etc., 
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and  in  this  way  attempting  to  make  more  efficient  use 
of  available  core  storage.   The  desire  to  permit  such 
a  process  accounts  for  a  number  of  important  pecularltles 
of  the  Nu-Speak  freespace-provlding  mechanisms. 

In  the  regularization  process  described  above,  heads 
(to  which  program  locations  may  refer)  must  remain  unmoved. 
For  this  reason  Nu-Speak  makes  an  effort  to  keep  all  list- 
heads  confined  to  as  limited  a  region  as  is  feasible;  more 
precisely,  to  a  belt  in  core  extending  from  the  top  of  the 
program  area  to  the  bottom  of  the  area  used  for  list 
elements  other  than  heads .   The  following  diagram,  showing 
the  utilization  of  core  storage  by  Nu-Speak,  will  make 
this  point  clearer. 
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When  a  Nu-Speak  macro  requires  a  pair  of  locations  to 
form  a  llsthead  (e.g.  C0PYT0,  CREATE);  the  required 
locations  are  supplied  from  the  head  junkplle,  if  any 
such  heads  are  available.    '-■  If  no  such  heads  are 
available,  the  list  item  stored  in  the  lowest  pair  of 
core  positions  above  the  head  area  is  moved  to  another 
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location,  this  position  used  for  the  newly  formed  head,  and 
the  head  area  boundary  advanced  upward  a  corresponding 
number  of  locations. 

Prom  the  programmer's  point  of  view,  this  means 
that  the  actual  storage  location  of  a  list  item  is  quite 
indeterminate,  and  that  list  items  (other  than  heads), 
once  found  and  left  cannot  be  found  again  by  returning 
to  a  given  core  position.   (There  is,  moreover,  another 
process  which  will  shift  the  location  in  core  of  a  given 
data  item:   the  automatic  breaking  of  a  block  of  data  in 
a  list  when  an  additional  item  of  data  is  INSERT-d  in  its 
middle,  or  REM0VED  from  its  middle,  etc.). 

It  follows  from  the  above  that  any  list  operation 
but  NEXT,  PREV,  TEDATA  and  the  other  tests,  JUMPT0, 
NAMLIS,  and  CLERNM,  may  change  the  actual  core  location 
of  a  word  of  data.   To  be  able  to  return  to  a  word  of 
data,  even  when  the  central  processor  Jumps  out  of  the 
list  containing  the  word,  the  following  procedures  may 
be  used. 

a.  Keep  a  count  of  the  location  of  the  word 
relative  to  its  listhead,  and  return  to  it  by  the 
sequence 

JUMPT0      listhead 

BEGIN  D0BEG        END,1,=1,N 

NEXT 

END  D0END       BEG,1 
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where  N  is  the  position  number  of  the  desired  item  in 
its  list. 

b.   If  the  list  is  long,  the  above  procedure  may 
be  unduly  time-consuming.   In  this  case,  the  following 
procedure  may  be  used.   Before  leaving  the  list  item 
in  question,  execute 

NCPLT0      auxiliary  name 


then  return  by 

JIMPT0      listhead 
PREV 

CUPL        auxiliary  name 
c.   The  two  procedures  described  above  may  be  used 
without  any  special  preparation  within  recursive  systems 
of  SUBR's.   In  situations  in  which  recursion  is  not  used, 
the  following  faster  procedure  may  be  used.   Before 
leaving  the  data  item  to  which  a  subsequent  return  is 
to  be  made,  execute  the  following  lines  of  machine  code, 
or  some  similar  lines: 

SAVEXRl 

BREAK  BL0CK  0P  DATA  IF  NECS 
SAVE  XR7 

GET  IDENTIFIER  WD 
SUPPLY  ADR.  0P  NEXT  WD 
XR1=-(ADR  0F  CURRENT  WD) 
NEXT  0P  CURRENT  WD  BEC0MES 
*  NEXT  0P  AUXIL 
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SXA 

AUXILl 

TESTBL 

SXA 

AUXILl+1 

PIA 

STA 

*+l 

LDC 

**,! 

STA 

AUXIL 

SCD 

AUXIL,! 

C0RRECT  WD  BEC0iy[ES 
PREV  0P  AUXIL 

PAC 

i7 

X7=-(ADR  0F  NEXT  WD) 

CLA 

AUXIL+2 

PICK  UP  ADRESS  0P  AUXIL 

STL) 

0.7 

AUXIL  BEC0MES  PREV 
0F  NEXT  BL0CK 

STA 

0,1 

AUXIL  BEC0MES  NEXT 
0F  CURRENT  BL0CK 

TRA 

AUXILl 

SKIP  0VEK 
ST0RAGE  L0CATI0NS 

AUXIL 


EVEN 
0NE 

PZE 


0,0,0 


0 


L0CATI0NS  0F  W0RD-PAIR 
T0   BE  INSERTED 
SEC0ND  WD  0F  PAIR 


PZE  AUXIL, 0,AUXn.  ST0RED  ADRS .  0F  AUXIL 
AUXILl   AXT      **,1         RESTORE  XRl 
AXT     **,7        RES10RE  XR? 

•  •  • 

The  above  routine  will  Insert  the  auxiliary  'data  Item' 
contained  In  the  pair  of  locations  AUXIL  and  AUXIL+1 
Into  the  list;  since  these  locations  lie  In  the  program 
area,  and  thus  below  the  head  area,  none  of  the  list 
processes  can  shift  the  physical  position  of  this  Item. 
Return  may  be  made  with  the  sequence 
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CLA 

AUXIL 

PDC 

,7 

XR 7= -(CURRENT  IDENT .  ADR) 

PAC 

,6 

XR6=-(NEXT-IDENT.  ADR) 

STA 

0,7 

REST0RE  PR0PER  NEXT  0P 
CURRENT 

STD 

0,6 

REST0RE  PR0PER  PREV.  ELT 

0P  NEXT 

DLD 

0,7 

REST0RE  MQ 

PAI 

REST0RE  SI 

LXA 

AUXTT,1+1,7 

REST0RE  XR7 

LAC 

llstheadj,6 

REST0RE  XR6  T0 
-(LISTHEAD  IDENT  ADR) 

A  suitably  modified  version  of  this  procedure  can  be  used 
in  the  context  of  recursive  subroutines. 

In  the  special  case  in  which  no  list  creation  can 
logically  intervene  between  leaving  a  given  list  element 
and  returning  to  it  subsequently,  the  following  simple 
pair  of  macros  is  provided  to  enable  the  return: 


SAVE 


SAVE 


MACR0 

A 

STQ 

A 

STI 

A+1 

SXA 

A+2,7 

SXD 

A+2,6 

END 

-  74  - 


GET 


MACR0 

A 

LDQ 

A 

T,DI 

A+1 

LXA 

A+2,7 

LXD 

A+2,6 

END 

GET 
The  use  of  these  macros  should  be  plain. 

B7.   The  Macros  EREESP(ace)  and  FREEHD. 

The  macros  PREESPACE  and  FREEHD  have  the  form 
PREESPACE 
and 

FREEHD 
respectively.   When  the  instruction  FREESPACE  is 
encountered,  the  address  of  the  first  (even  location 
member)  of  a  pair  of  locations  suitable  for  forming  a 
new  list  element  will  appear  in  the  address  portion  of 
the  otherwise  cleared  accumulator.   FREEHD  has  much  the 
same  effect,  but  provides  a  pair  of  locations  suitable 
for  forming  a  new  head.   The  macro  FREEHD  should  be  used 
with  caution,  since  it  has  the  following  side  effects: 

i.   The  contents  of  the  sense  indicator  are  taken 
as  the  identifier  word  of  a  given  list  element.   This 
word  is  stored,  and  when  restored  may  have  modified  address, 
and/or  decrement,  and/or  tag  portion,  if  the  rearrangement 
of  the  storage  of  link  elements  in  core  consequent  on  using 
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FREEHD  has  moved  the  "next"  or  "previous"  element  of  this 
list  element,  or  a  word  originally  in  the  same  block  as 
this  list  element,  etc. 

ii.   The  process  of  rearranging  list  elements  in  core 
which  may  be  consequent  on  using  FREEHD  ass"ujnes  that  all 
lists  have  their  normal  structure.   Thus  FREEHD  should 
never  be  used  unless  all  "next  pointers"  and  "previous 
pointers"  of  all  lists  are  appropriately  set.   (The 
Nu-Speak  list  operations  will  never  disturb  this  condition, 
but,  unless  the  programmer  takes  care,  his  own  intermediate 
steps  of  additional  PAP  list  processes  might.) 

In  view  of  the  touchiness  of  FREEHD,  the  programmer 
will  normally  prefer  to  use  CREATE  in  order  to  obtain  a 
new  listhead. 

The  following  remarks  summarize  the  effect  of  the 
Nu-Speak  list  operations  on  the  number  of  references  to 
the  lists  they  concern  NEXT,  PREV,  CUPL,  INSERT,  REM0VE, 
JUMPT0,  SUBLIS,  and  the  various  tests  (TEHEAD,  etc.)  have 
no  effect.   NCPLT0  does  not  affect  the  reference  number 
of  the  list  which  it  breaks  up;  the  computer  is  left 
looking  at  the  head  of  the  newly  broken  off  second  part 
of  the  list,  which  hence  has  a  reference  niimber  of  1. 
CREATE  does  not  affect  the  number  of  references  to  any 
list,  but  leaves  the  computer  looking  at  the  head  of  the 
newly  created  list,  which  therefore  has  a  reference 
number  of  i;   NAMLIS  increases  the  number  of  references 
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to  the  newly  named  list  by  1;  CLERNM  does  the  opposite. 
HANG  increases  the  member  of  references  to  the  subllst 
being  hung  by  Ij  and  UNHANG  decreases  this  same  reference 
number  by  1. 

b8.   Miscellaneous  macros. 

In  a  Nu-Speak  assembly,  the  control  PRNTMC  replaces 
the  FAP  control  PMC  (print  macro-generated  cards).   Use 
of  PMC  will  fall  in  erratic  ways. 

The  control  card  HEADER  may  be  used  to  provide  a 
heading  character;  these  characters  will  lae   provided  in 
sequence  from  the  list  Z,    X,    Y,     ...,    k,    9>  ••'>    1;  other 
characters  chosen  from  this  list  will  head'the  variables 
occurring  in  SUBRS .   The  heading  of  a  section  of  code 
can  be  terminated  by  the  normal  PAP  card  HEAD  0. 

B9.   Forbidden  macro-words  and  entry  symbols. 

The  following  symbols  are  used  as  intermediate 
macro-names  in  Nu-Speak,  and  should  never  be  used  as 
macro-names  by  a  programmer  using  Nu-Speak  who  has  not 
pondered  long  over  the  profound  changes  in  the  system 
thereby  introduced. 

P0N,..,  P0P...,  Q0N...,  PSW...,  H0D...,  HED..., 
HEADER,  HAD...,  BGS o . . ,  STR . . . ,  RST...,  SBl . . . ,  SB2..., 
IRS...,  MICR0,  RPR...,  0PA...,  IP0 . . . ,  TIMESA,  0VERA, 
ST0...,  CLA. . .  ,  MUGR0  . 
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The  following  wierd  symbols  are  used  as  control 
symbols  or  as  entries  to  various  Nu-Speak  programs,  and 
should  not  be  used  by  the  Nu-Speak  user  unless  he  knows 
what  he  is  doing. 

..0.. .,  . .1. ..,  . .2. . .,  . .3-. •,  . .5...,  ..6. . ., 
..1...,     ..9. ..,     . .A...,  ..B. . .,  . .C. ..,  . .D..., 
..E...,  ..F...,  ..G...,  ..H...,  ..J...,  ..K...,  ..N..., 
..0...,  ..Z...,  )....(,  ).[{.{,     ).(..(,  ).)(.(,  ..IN..., 
..NN...,  ..0T...,  ..0G...,  ..0W...,  )()(.),  )))))), 
..HT..  , 

EXHAUS,  C0NL0C,  (ERRl)  through  (ER12)  and  (ER20), 
..BN..,  ..BB..,  ..B0..,  ..BC..,  . .LNK2,  (.LG.),  (.LB.), 
.R.PLT,  .LET...,  .L2..,  ..LO..,  .R 

HDCNTR,  CARDSW,  BUGZZQ,  XI ,  X2 ,  X3 , 

X5 ,    X6 ,  X7 ,    SI ,  MQ ,  1 ,  2 , 

XXSIXX,  XXX 4XX,  XXMQXX,  REPTSW,  C0UNTR,  C0UNTO,  MULTSW, 
..GG..,  ..GH..,  ..GI.. 

BIO .   Special  Procedures  for  Dealing  with  Self-Reflexive 
List  Structures. 

The  S-bit  and  first  20  bits  of  the  second  word  of  a 
listhead  as  formed  by  the  Nu-Speak  list-creating  opera- 
tions CREATE,  NCPLT0,  C0PYT0  will  always  be  blank;  and 
the  remaining  Nu-Speak  list  processes  will  not  affect  these 
bits.   (A  similar  remark  can  be  made  concerning  links.) 
If  the  programmer  takes  the  precaution  never  to  tamper 
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with  the  S-blt  of  these  listhead  words,  the  following 
procedures  may  be  used  to  deal  with  reflexive  list 
structures . 

I.  A  recursive  routine  MARKER,  called  by  the 
sequence 

CALL      MARKER,  list name 
where  "llstname"  Is  the  name  of  a  list  In  a  self-reflexive 
structure,  Is  available.   This  Instruction  will  cause  the 
1-blt  of  the  second  word  of  the  list  head  "llstname", 
every  one  of  Its  subllsts,  every  subllst  of  a  subllst, 
etc .,  to  be  set  to  1. 

II.  Recursive  procedures  may  then  be  applied  to 

the  lists  of  a  self-reflexive  structure  and  their  subllsts 
provided  that 

a.  A  subllst  Is  marked  as  "entered"  by  setting  the 
1-blt  of  the  second  word  of  Its  head  equal  to  zero  as 
soon  as  It  is  reached  by  the  recursive  procedure. 

b.  The  recursive  procedure  avoids  entering  a  list 
whose  head  shows  that  it  has  already  been  entered. 

ill.   In  view  of  the  catastrophe  which  will  always 
ensue  on  erasing  a  subllst  of  a  list  either  before 
unhanging  the  subllst  or  before  erasing  the  main  list, 
special  care  must  be  taken  in  the  erasure  of  self- 
reflexive  list  structures  or  subllsts  thereof.   These 
Include: 
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a.  To  erase  the  whole  structure,  use  a  recursive 
procedure  as  above  to  UNHANG  every  sublist  of  every  list, 
creating  at  the  same  time  a  (non-redundant)  auxiliary 

list  of  the  locations  of  all  the  llstheads  of  the  structure 

b.  To  erase  one  list  of  a  structure,  use  a  recursive 
procedure  as  above  to  UNHANG  it  from  every  list  of  the 
structure.   Then  erase  the  list  in  question. 

Bll.   The  Form  of  a  Nu-Speak  Deck. 

In  an  attempt  to  save  as  much  core  space  as  possible 
from  unessential  uses,  Nu-Speak  utilizes  chaining. 
Nu-Speak  Jobs  are  chained  as  follows: 

a.   A  first  link,  created  by  the  chain  control  routine 

*  CHAIN      (101,5) 

This  link  contains  the  main  program  section.   A  second 
link  contains  the  error  and  freespace-exhausted  messages 
and  procedures,  and  is  created  by  a  chain  control  card 

*  CHAIN      (102,3) 

*  FAP 

TRA        $..LNK2 

END 

These  conventions  cause  the  Nu-Speak  deck  to  have 

the  following  form 
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1  User's  *ID  card,  either  with  or  without  an  *XEQ 
execution  order  card 

2  Nu-Speak  control  deck,  always  provided  already- 
containing  all  necessary  ^FAP  and  chain-creating 
control  cards,  and  containing  binary  cards  for 
first  (preliminary)  link  programs.   This  deck 
will  cause  a  single  Instruction,  TSX  $..W...,4 
to  assemble  (which  executes  a  preliminary 
initialization  before  returning  to  the  user's 
program) . 

3  User's  symbolic  program,  terminated  by  an  END  card 
h     User's  binary  decks 

5  Nu-Speak  binary  decks,  either 

I.  minimum  package, 

II.  string  manipulation  package, 
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ill.  total  package^  or 

iv.   any  of  the  above,  plus  the  "debug"  binary  package 
6  Data  cards.  If  any,  preceded  by  the  control  *DATA 


,  By  installing  some  of  the  Nu-Speak  programs  on  the 
library  tape,  and  by  installing  the  macros  on  an  auxiliary 
update  tape,  various  of  these  deck  sections  can  be 
abbreviated  or  eliminated. 

To  provide  a  subtitle  for  his  output,  the  user 
can  either 

a)  put  a  *FAP  immediately  after  his  first  *ID 

and  *XEQ  cards,  followed  by  the  title  of  his  program,  or 

b)  use  an  appropriate  TTL  card  early  in  the 
symbolic  deck. 

CI.   The  Auxiliary  Routines  WRTLIS  and  INLSTR . 
a)   Output  of  List  Structures . 

For  writing  out  lists  or  list  structures,  three 
routines  are  provided. 

WRTSTR  --  a  routine  for  writing  out  any  list  structure 
WRINGS  --  a  routine  for  writing  out  a  non-reflexive 

list  structure 
WRTLIS  —  a  routine  for  writing  out  the  elements  of 

a  single  list. 
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These  three  list  output  routines  write  out  a  list 
or  an  entire  structure,  ten  list  elements  per  line,  in 
both  alphabetic  and  octal  formats.  (A  list  element  is 
a  head,  link,  or  data  element.)  In  addition,  the  word 
HEAD  or  LINK  is  written  out  next  to  a  list  element 
which  is  a  head  or  link. 

The  routine  MRTLIS  writes  out  only  the  elements 
of  a  single  list;  it  does  not  descend  to  sublists. 
It  is  called  by  a  statement  of  the  form 

CALL       WRTLIS,  LIST 
where  list  is  a  listname. 

Both  WRINGS  and  WRTSTR  recursively  write  out  the 
entire  structure  of  a  list.   WRTSTR  calls  MARKER  and 
can  write  out  any  list  structure,  even  one  which  is 
reflexive.   WRINGS  does  not  call  MARKER  and  can 
successfully  write  out  only  a  non-reflexive  list 
structure.   These  routines  are  called  by  statements 
of  the  form 

CALL        WRTSTR,  LIST 
and 

CALL        WRINGS,  LIST 

These  routines  perform  the  recursive  output  of 
list  structures  as  follows: 

1)  The  argument  of  the  routine  becomes  the  "present" 
list,  which  is  written  out  in  its  entirety.  (The 
location  of  the  listhead  is  written  out  prior  to 
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the  list  itself.)   The  present  list  is  marked 
as  having  been  processed. 
2)  The  first  previously  unprocessed  subllst  of  the 
"present"  list  Is  searched  for.   If  such  a  list 
exists.  It  becomes  the  argument  of  the  recursive 
routine  (step  1)  .   Otherwise,  the  substructure 
of  the  "present"  list  has  been  completely  written 
out;  exit  Is  made  from  this  level  of  the  recursive 
routine . 

b)   Input  of  List  Structures 

The  subroutine  INLSTR  Is  provided  for  the  Input  of 
data  into  list  form.   The  statement 

CALL       INLSTR,  NAME 
will  cause  the  data  which  is  next  on  line  to  be  read  from 
the  monitor  input  tape  to  be  read  into  core  as  a  list  with 
name  NAME.   The  data  to  be  read  in  by  INLSTR  should  be  in 
a  regular  monitor  data  deck  which  is  headed  by  a   -^DATA 
card.   The  data  to  be  put  into  list  form  should  have  the 
format  described  below. 

Data  Format 

A  list  is  begun  on  and  continued  on  cards  with  a  "1" 
in  column  1,  a  series  of  5  symbol  redefinitions  (described 
below)  in  columns  2  through  6,  and  the  actual  list  elements 
and  list  control  characters  beginning  in  column  7  and  not 
running  beyond  columan  72.   A  list  is  ended  by  a  blank  card. 
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List  Control  Characters 

The  following  characters  have  special  control 
functions  which  communicate  to  INLSTR  the  form  In  which 
the  list  Is  to  be  stored  In  core.   These  characters 
cannot  he  used  as  letters  of  the  actual  list  elements 
unless  redefined  In  the  symbol  redefinitions  field  of 
the  card  throughout  which  the  redefinitions  are  to 
hold. 

These  are  the  control  characters: 
,     The  comma  Is  used  to  separate  list  elements. 

A,  BC,  BETA,  . .. 
(    The  left  parenthesis  Is  used  to  begin  a  subllst. 
Thus,  the  data 

A,  BC,  BETA  (SUB,  LIST 
will  cause  a  subllst  beginning  with  the  words 
"SUB"  and  "LIST"  to  be  hung  on  the  list  of  which 
"A",  "BC",  and  "BETA"  are  elements.   The  left 
parenthesis  must  be  the  symbol  In  column  seven 
of  the  first  card  of  a  list. 
)    The  right  parenthesis  Is  used  to  end  a  subllst. 
Thus,  the  data 

A,  B,  (C,  D),  E 
will  cause  the  data  word  E  to  be  an  element  of 
the  same  list  as  "A"  and  "B" .   The  main  list 
must  be  ended  by  a  right  parenthesis. 
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$    The  dollar  sign  Is  used  to  signify  the  end  of  a  card. 
Thus,  the  data 

A,  B$ 
will  cause  INLSTR  to  begin  processing  the  next 
data  card  In  the  deck  after  processing  "A"  and  "B" . 

/    The  slash  Is  used  to  Indicate  that  the  word 

following  Is  to  be  recognized  as  a  decimal  nxAmber 
and  Is  to  be  converted  Into  a  36  bit  binary  fixed 
or  floating  point  core  word.   A  minus  sign  preced- 
ing the  number  will  cause  It  to  be  stored  In  core 
with  the  S-blt  on  (negative  number) .   The  absence 
of  a  minus  sign  designates  the  number  as  positive. 
The  plus  sign  should  never  be  used.   The  appear- 
ance of  a  decimal  point  In  the  number  will  cause 
It  to  be  converted  to  a  floating  point  core  word. 
The  absence  of  a  decimal  point  designates  the 
nuunber  as  an  Integer.   The  magnitude  of  an  Integer 
must  not  exceed  2.^-^-   \,    and  floating  point  quantities 
should  have  no  more  than  8  significant  digits. 
The  appearance  of  an  0  directly  after  the  slash 
causes  the  word  following  to  be  taken  as  an  octal 
integer.   An  octal  integer  may  have  from  0  to  12 
octal  digits. 
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A  list  may  be  continued  from  one  card  to  another 
by  simply  ending  the  first  card  In  the  pair  with  a  dollar 
sign  and  continuing  where  the  list  was  cut  off  In 
column  7  of  the  next  card.   Columns  1-6  of  the  second 
card  must  contain  the  normal  control  Information  (see 
below) .   Single  words  cannot  be  continued  from  one  card 
to  another . 

Redefinitions  of  Control  Characters 

Since  It  Is  sometimes  necessary  to  treat  the  above 
special  characters  as  actual  letters,  to  be  read  Into 
core  as  part  of  data  words  rather  than  as  symbols  which 
only  perform  a  control  function  and  which  are  not  read 
Into  core,  an  optional  redefinition  feature  is  provided. 
To  redefine  a  control  character,  place  a  valid  BCD 
character  in  the  appropriate  column  of  the  redefinition 
field  of  the  card  throughout  which  the  redefinition  is 
to  hold.   The  inserted  character  will  be  taken  to  have 
the  function  of  the  control  character  it  redefines.   The 
old  control  character  is  then  free  for  use  as  an  actual 
letter.   Redefinitions  hold  only  over  the  card  on  which 
they  appear.   A  blank  in  a  redefinition  column  causes 
the  corresponding  control  character  to  remain  as  shown 
on  previous  pages (control  characters).   The  original 
cbntrol  characters  are  reinstated  at  the  beginning  of 
the  processing  of  each  new  card. 
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The  redefinition  columns  are  as  follows; 
Column  2  redefines  ( 


II 

3 

II 

$ 

tl 

4 

II 

) 

II 

5 

II 

/ 

II 

6 

II 

) 

Thus,  to  enable  the  word  "AL,PHA"  to  read  into  core  as 
the  single  word  "AL,PHA"  rather  than  as  the  two  words 
"AL"  and  "PHA,"  a  convenient  symbol,  say  "*",  should  be 
Inserted  in  column  ^  of  the  card  on  which  "AL,PHA"  is 
found.   The  symbol  "*"  should  then  be  used  throughout 
the  data  card  instead  of  ","  where  word  separation  is 
necessary.   In  effect,  "*"  becomes  ","  and  ","  is 
freed  for  use  as  a  normal  letter  to  be  read  into  core 
in  regular  data  fashion.   The  following  example  should 
illustrate  the  use  of  INLSTR . 
The  statement 

CALL       INLSm,  LSTNAM 
if  used  on  the  following  data 

Cols.     12  3  4  3  g  7 


GDI  1  (N0W,IS(THE(TIME$ 

CD2  1  *      =        F(0R=*,ALL,=G00D$ 

CD3  1     X   *      =   MEN^T0,,,=C$0ME==T0=X 
CD4 


w 


ill  cause  these  lists  to  be  placed  in  core: 


LSTNAM 

Head 

N0W 

llstl  • 

Head 

THE 

llst2 

Head 

TIME 

Name  List  Elements 

IS       pointer  to  llstl    T0 

pointer  to  list2 
P(0R     pointer  to  list^    C$0]yiE 
list3    Head    ,ALL,   G00D     MEN  T0 , , , 

The  computer  will  be  left  looking  at  the  head  of  LSTNAM. 

An  error  message  and  a  subsequent  call  exit  statement 
will  be  produced  should  a  list  contain  a  word  of  more  than 
six  BCD  characters  or  an  unbalanced  parenthesis. 

C2.   An  Auxiliary  Package  of  Subroutines  for  Letter 
Manipulation . 

The  Nu-Speak  letter  macro  package  enables  the 
programmer  to  manipulate  letters"  within  words  in  a 
manner  similar  to  the  manipulation  of  words  within 
blocks.   The  letter  macros  will  normally  be  used  on 
data  words  in  logical  6  letter  BCD  format. 

Nu-Speak  Letter  Conventions 

The  computer  is  said  to  be  looking  at  a  letter  when: 

1)  A  copy  of  the  ID  of  the  word  in  which  the  letter  is 
contained  is  in  the  SI. 

2)  The  word  in  which  the  letter  is  contained  is  found 
in  the  MQ  with  the  letter  rotated  left  into 
positions  29-35  of  the  MQ. 

5)   The  letter  itself  appears  in  positions  29-35  of  the  AC. 


(Note:   This  convention  Is  violated  by  certain 
of  the  letter  macros,  see  below.) 

4)  XR7  contains  the  number  of  the  word  containing 
the  letter  in  its  block. 

5)  XR5  contains  the  number  of  the  letter  in  its  word 
counting  from  left  to  right  as  the  word  appears 
in  storage. 

In  each  program  using  letter  processing,  the  code 
AXT       0,  5 
should  be  executed  before  the  first  of  the  letter  macros 
is  reached  . 

The  BCD  blank,  octal  6o ,    is  treated  as  a  normal 
character  by  the  letter  macros.   The  special  Nu-Speak 
functional  blank,  octal  JJ ,    should  be  used  when  the 
absence  of  a  normal  BCD  character  is  required. 

The  macros  NEXT  LETTER  and  PREVIOUS  LETTER  have 
the  form: 

NEXTL 
and 

PREVL 
These  macros  cause  the  computer  to  look  at  the  next  and 
previous  "non-functional  blank"  character  in  the  word 
respectively.   Nu-Speak  functional  blanks  are  skipped 
but  will  affect  the  count  in  XR5.   Execution  of  a  NEXTL 
while  the  computer  is  looking  at  the  end  of  a  word, 
(XR5  =  6),  will  cause  the  CPU  to  look  at  the  first 
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non-functional  blank  character  In  the  next  word  of  the 

list.   Should  the  next  word  in  the  list  be  non-data  (i.e. 

head  or  link)^  the  CPU  will  look  at  it  in  the  normal 

Nu-Speak  fashion^  and  XR5  will  be  set  to  0.   The  analogous 

feature  is  included  in  PREVL.   (Note:   If  PREVL  should  run 

into  a  non-data  word,  XR5  will  be  set  to  7,)   Execution 

of  a  NEXTL  or  PREVL  while  the  computer  is  looking  at  a 

non-data  word  will  cause  the  CPU  to  look  at  the  first 

non-functional  blank  character  in  the  NEXT  and  PREVIOUS 

words  respectively.   The  new  letter  found  by  either 

NEXTL  or  PREVL  will  always  be  placed  in  positions  29-35 

of  the  AC. 

Please  note  the  following  examples  of  the  use  of 

NEXTL  and  PREVL: 

Note:  ¥£'      is  taken  to  follow  WD  ■,    in  its  list, 
n  n-1 

XR5  should  initially  be  set  to  0  by  the  programmer, 

WD-,_  =  head  of  LIST, 

WDg  =  A(T7)(77)(77)P(77) 

TO^  -  (77)X(77)(77)(77)(77) 

WLi^  =  (77)(77)(77)(77)(77)T 

WD^  =  link  pointing  to  subllst  1 

WD/-  =  link  pointing  to  subllst  2 
MACRO  MQ  XR3 

JUMPT0  LIST         WD^  0 

NEXTL  (77)(77)(77)P(77)A  1 

NEXTL  (77)A(77)(77)(77)P  5 

NEXTL  (77)(77)(77)(77)(77)X  2 
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MACRO  (Cont'd.)            MQ  XR5 

NEXTL  (T7)(77)(77)(77)(77)T  6 

NEXTL  WD^  0 

NEXTL  WDg  0 

PREVL  \m^  7 

5 

PREVL  (77)(77)(77)(77)(77)T  6 


Note  that  if  the  contents  of  the  MQ  are  changed,  for  example 
at  step  (4),  the  results  at  step  (5)  would  not  be  altered. 
All  letter  macros  refer  to  the  contents  of  XR5  and  of  core 
for  data  on  which  to  base  their  operations  —  not  to 'the  MQ. 

The  macro  REPLACE  LETTER  has  the  form: 
REPLET    A 
The  macro  will  replace  the  letter  being  looked  at  with 
the  letter  in  positions  29-35  of  location  A.   The  change 
will  appear  in  the  AC,  the  MQ,  and  in  storage.   The  CPU 
will  be  left  looking  at  the  new  letter. 

To  delete  a  letter,  two  procedures  may  be  used: 

1)  The  code  REPLET  =  077  will  replace  the  letter  being 
looked  at  by  (77).   Thus,  in  effect,  the  letter  is 
deleted  since  the  macros  NEXTL  and  PREVL  skip  functional 
blanks.   The  CPU  will  be  left  looking  at  the  functional 
blank.   The  AC  will  be  set  to  77- 

2)  The  macro  DELETE  may  be  used.   DELETE  will  replace  the 

letter  being  looked  at  by  a  functional  blank  and  will 

cause  the  CPU  to  look  at  the  next  letter  in  the  list  (i.e 

DELETE  automatically  calls  NEXTL) .   Should  the  CPU  be 

looking  at  a  non-data  word  upon  executing  a  DELTL,  the 
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entire  data  word  will  be  deleted  (i.e.  as  with  REMQVE) . 
The  CPU  will  then  be  left  looking  at  the  next  word  in 
the  list  but  not  at  any  particular  letter  in  the  word. 
XR5  will  be  set  to  zero. 

The  macro  TEST  AND  BREAK  ¥^RD  has  the  form 
TESTL 
The  macro  will  check  to  see  whether  the  letter  being  looked 
at  by  the  CPU  is  the  last  letter  in  its  word  (i.e.  if  XRf  =  6) 
If  it  is,  the  macro  will  perform  no  additional  function.   If 
it  is  not,  the  macro  will  split  the  word  containing  the 
letter  being  looked  at  into  two  words  in  a  manner  illustrated 
by  the  following  example: 

before  TESTL,  XR5  =  4,  MQ  =  ?^HMATZ,  and  WD.  =  MATZAH 
after  TESTL,  XR5  =  4,  MQ  =  (77) (77)MATZ,   WD^=  MATZ(77) (77) , 
and  ^i]+l   "  (77)(77)(77)(77)0H 

WD,.  -,  will  be  inserted,  in  normal  Nu-Speak  fashion,  after 
WD   in  the  list.   The  CPU  will  be  left  looking  at  the  same 
letter  as  it  had  before  the  execution  of  the  TESTL. 
The  macro  INSERT  LETTER  has  the  form 
INSERL    L?fC 
The  macro  will  cause  the  letter,  or  letters,  found  in 
location  L0'C  to  be  inserted  directly  after  the  letter  being 
looked  at.   If  the  number  of  letters  to  be  Inserted  is  less 
than  6,  the  surplus  digits  in  L^'C  must  contain  functional 
blanks.   The  Insert  -will  be  made  in  the  following  manner: 

1)  A  TESTL  will  be  executed 

2)  An  INSERT  L^C  will  be  executed 

Please  note  the  following  example: 
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Before  INSERL  -  XR5  =4   MQ  =  ^HMATZ   WD  =  MATZ0H 

L^C  =  (77)(77)XYQ(77) 
After  INSERL   -  XR5  =3   MQ  =  YQ(77) ( 77) (77)X 

WDj^  =  MATZ(77)(77) 
^N+1  =  (77)(77)XYQ(77) 
^N+2  "  (77)(77)(77)(77)?^H 
Note  that  letters  X,  Y,  and  Q,  are  In  effect  inserted 
between  Z  and  0.   This  is  due  to  the  fact  NEXTL  and 
PREVL  skip  functional  blanks. 

The  CPU  will  be  left  looking  at  the  first 
non- functional  blank  letter  in  L^C . 

The  macro  IP  LETTER  has  the  form 
IPLET     A,  B,  C 
If  the  letter  contained  in  positions  29-35  of 
location  A  is  identical  with  the  letter  being  looked  at 
by  the  CPU,  control  will  be  transferred  to  location  B. 
If  not,  control  will  be  transferred  to  location  C. 
The  macro  C0UPLE  LETTER  has  the  form 
CUPLL     A 
The  macro  will  form  a  TESTL  word  break  directly  after 
the  letter  being  looked  at  and  will  then  execute  a 
Nu-Speak 

CUPL      A 
XR5  will  be  set  to  0.   Thus,  in  effect,  the  letters  of 
the  list  named  A  are  inserted  directly  after  the  letter 
at  which  the  CPU  was  looking,  and  directly  before  the 

letter  which  preceded  it. 
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The  macro  UNC0UPLE  LETTER  has  the  form 

NCPLTL    A 
The  macro  will  form  a  TESTL  word  break  directly 
after  the  letter  being  looked  at  by  the  CPU  and 
will  then  execute  a  Nu-Speak 

NCPLT0    A 
XR5  will  be  set  to  0.   Thus,  in  effect,  all  the 
letters  in  the  list  which  had  followed  the  letter 
under  examination  are  UNCOUPLED  from  the  list. 

03 •   An  Example  of  Nu-Speak  Applications  Programming: 
P0LPAC . 

The  P0LPAC  package  is  coded  in  Nu-Speak  and  is 
designed  for  substituting  ,  partially  differentiating, 
and  algebraically  manipulating  symbolic  polynomials. 

A  P0LPAC  polynomial  is  a  Nu-Speak  list  structure 
of  the  following  form: 

The  polynomial  is  a  list  which  consists  entirely 
of  links.   The  sublist  to  which  each  link  points  is  a 
term  of  the  polynomial.   The  first  element  of  each  term 
is  a  floating  point  number  and  is  the  coefficient  of 
the  term.   Succeeding  elem.ents  of  the  term  are  variables 
raised  to  powers,  each  in  the  format 


VARIABLE- 

EXPONENT 

S,l  20  21         55 
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That  is,  the  variable  name  occupies  positions  S,    1-20, 
and  the  exponent  Is  a  right-adjusted  address  integer. 
The  coefficient  is  always  the  first  data  element 
of  a  term.   Within  a  given  term,  the  variables  are 
arranged  according  to  Increasing  numeric  order,  with 
the  S-blt  treated  in  the  sense  of  the  "logical"  machine 
Instructions . 

Example: 

2   2 
The  polynomial  1.5  +  3-5  x  y   would  be 

generated  as  follows: 

CREATE  TERMl 

INSERT  1 . 5 

CREATE  TERM2 

INSERT  5 . 5 

INSERT  X2 

INSERT  Y3 

CREATE  P0LY 

HANG  TERMl 

HANG  TERM2 


TERMl 

PZE 

TERM2 

PZE 

P0LY 

PZE 

1.5 

DEC 

3-5 

DEC 

X2 

BCI 

Y3 

BCI 

1.5 

3-5 

1, 

X002 

1, 

Y003 
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At  this  point  we  will  define  a  checklist,  which  is 
used  to  truncate  the  high-order  terms  of  a  polynomial. 
A  checklist  has  the  same  form  as  a  term  of  a  polynomial 
except  for  the  absence  of  a  coefficient  in  the  checklist. 
A  term  is  said  to  exceed  a  checklist  if  and  only  if  any 
one  of  the  variables  in  the  checklist  appears  in  the 
term  raised  to  a  power  higher  than  its  exponent  in  the 
checklist . 

The  P0LPAC  routines  are  as  follows: 
Subroutine  C0MPAR  -  compares  a  given  term  to  a  checklist 
Calling  sequence:   CALL  C0MPAR,TERM,CKLIS,YESN0 
TERM     is  the  name  of  a  term  of  a  polynomial 
CKLIS    is  the  name  of  a  checklist 
YESN0    is  a  core  location. 
Upon  return  from  C0MPAR,  YESN0  is  zero  if  and  only 
if  TERM  does  not  exceed  CKLIS.   Note:   The  variables 
of  CKLIS  must  be  alphabetically  ordered. 

Subroutine  0RDERR  -  orders  variables  within  a  term. 
Calling  sequence:   CALL  0RDERR,TERM1,TERM2 

TERM1,TERM2  are  both  names  of  terms. 
0RDERR  alphabetically  orders  the  input  term  TERMl, 
which  is  erased.  Upon  return  from  0RDERR,  TERM2 
is  the  alphabetization  of  TERMl . 
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Subroutine  ISSAME  -   tests  for  identity  of  two  terms. 
Calling  sequence:   CALL   ISSAME, TERM1;TERM2, YES N0 
TERMl,  TERM2   are  names  of  terms 
YESN0  is  a  core  location 

Upon  return  from  ISSAME,  YESN0  is   non-zero  if  and 
only  if  TERMl  and  TERM2  are  identical,  except  for 

coefficients.   Thus  the  terms  I.5  and  2.7  are 

2   ^  2  ^ 

identical,  as  are  I.5  x  y-^  and  3.7  x  y^  ,  but 

2.5  X  y   z  and  2.5  x  y  are  not. 

Subroutine  VARP0W  -  arranges  the  terms  of  a  polynomial 

according  to  the  exponent  of  a 
given  variable. 
Calling  sequence:   CALL  VARP0W,P0LYN,VAR, ERASE, P0LY0 
P0LYN,  P0LY0   are  polynomial  names 
VAR,  ERASE     are  core  storage  locations 
VARP0W         rearranges  the  terms  of  P0LYN  into 

a  new  pDlynomial,-  P0LY0,  by  ascending  order 
of  the  exponent  of  the  variable  name  in 
S,  1-20  of  the  word  VAR.   This  change  is 
effected  by  reordering  the  links  of  the 
list  P0LYN  into  the  new  list  P0LY0 .   The 
decrement  of  the  second  word  of  each  link 
of  P0LY0  contains  the  exponent  of  VAR  in 
the  term  to  which  the  link  points.   The 
■  variable  VAR  will  be  deleted  from  the  term 
of  P0LYN  if  and  only  if  ERASE  is  zero.   With 
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the  exception  of  the  possible  deletion 
of  the  variable  VAR,  the  terms  of  P0LYN 
will  not  be  changed  and  are  hung  from  P0LY0. 
The  list  P0LYN  (that  Is,  only  the  sequence 
of  links)  will  be  erased  by  VARP0M. 

Subroutine  C0LECT  -  collects  terms  of  a  polynomial. 
Calling  sequence:   CALL   C0LECT,P0LY 
P0LY    is  the  name  of  a  polynomial 
C0LECT   condenses  the  polynomial  P0LY  by  adding 

together  the  coefficients  of  matching  terms. 
(Two  terms,  TERMl  and  TERM2,  are  said  to 
match  if 

CALL   ISSAME, TERMl, TERM2,YESN0 
returns  a  zero  to  YESN0c)   Any  terms  which 
match  and  follow  a  given  term  of  P0LY  are 
unhung  from  P0LY  and  erased. 

Subroutine  P0LYMP   -  multiplies  two  polynomials  while 

truncating  according  to  a  checklist. 
Calling  sequence:   CALL   P0LYMP,P0LYA,P0LYB,CKLIS,P0LYC 
P0LYA,P0LYB,P0LYC   are  polynomial  names 
CKLIS  is  the  name  of  a  checklist 

P0LYC  contains  the  product  of  P0LYA  and  P0LYB. 
Only  those  terms  of  the  product  which  do 
not  exceed  CKLIS  appear  in  P0LYC .  Those 
terms  which  do  appear  are  alphabetically 
ordered.   P0LYA  and  P0LYB  are  unchanged. 


Subroutine  PRTIAL  -  partially  differentiates  a  polynomial 

with  respect  to  a  given  variable. 
Calling  sequence:   CALL  PRTIAL, P0LYA,VAR,P0L'YB 
P0LYA,  P0LYB  are  polynomial  names 
VAR  Is  a  core  storage  location 

PRTIAL  differentiates  P0LYA  with  respect  to  the 

variable  name  in  positions  S,    1-20  of  VAR. 
P0LYB  is  the  partial  derivative;  P0LYA  is 
left  untouched. 

Subroutine  SUBSTI   -   substitutes  a  polynomial  for  a  given 

variable  of  another  polynomial  while 

truncating  according  to  a  checklist. 

Calling  sequence:   CALL  SUBS TI,P0LYN,P0LYS, VAR, CKLIS, 

P0LY0 

P0LYN,  P0LYS,  P0LY0  are  polynomial  names 

CKLIS  is  the  name  of  a  checklist 

VAR  is  a  core  storage  location 

SUBSTI   substitutes  the  polynomial  P0LYS  for  each 

appearance  in  P0LYN  of  the  variable  whose 

name  appears  in  positions  S,  1-20  of 

location  VAR.   The  expanded  polynomial  is 

named  P0LY0.   P0LYN  is  destroyed.   P0LYS 

is  left  unchanged.   Only  those  terms  which 

do  not  exceed  the  checklist  will  appear  in 

P0LY0 . 
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Subroutine  P0LYRC   -  Tinds  the  reciprocal  of  a  polynomial 

to  a  given  degree,  while  concurrently 
truncating  according  to  a  checklist. 
Calling  sequence:   CALL  P0LYRC,P0LYN,DEG,CKLIS,P0LY0 
P0LYN,  P0LY0  are  polynomial  names. 
CKLIS         Is  the  name  of  a  checklist 
DEG  is  an  address  Integer 

P0LYRC   finds  the  reciprocal  of  a  polynomial 

P0LYN  according  to  the  following  algorithm: 
Let 

P0LYN  =   c(l  +  P0LYI) 
Then 

P0LY0  =  p^j^  =  ^  ^1  -  P^LYI  +  P0LYI^.  .  .  ) 
c   is  the  unique  non-zero  constant  term 
of  P0LYN. 

The  address  Integer  DEG  specifies  the  number 
of  terms  which  are  to  be  computed  in  the 
above  expansion.   Only  those  terms  of  the 
expansion  which  do  not  exceed  the  checklist 
will  appear  in  P0LY0.   P0LYN  is  left  unchanged 

Subroutine  P0L(})UT   -  polynomial  output  routine. 
Calling  sequence:   CALL  P0L0UT,P0LY 

P0LY  will  be  written  out  in  easily  understandable 
format. 
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